How to Schedule Regular Mastodon Account Exports With Cron

If you run a Mastodon instance or manage a personal account, you may want a local backup of your posts, followers, and other data. Mastodon provides a built-in account export feature through its web interface, but downloading it manually every week is tedious. This article explains how to automate Mastodon account exports using a cron job on Linux or macOS. You will learn how to authenticate with the Mastodon API, write a backup script, and schedule it to run daily or weekly.

Why Automate Mastodon Account Exports

Mastodon stores your account data on the instance server. If the instance goes offline or you decide to move to another server, having a recent export ensures you do not lose your content. The export includes your posts, media attachments, follower and following lists, and account settings. Manually visiting Settings > Import and Export > Export every few days is time-consuming and easy to forget. A cron job runs the backup silently in the background, giving you a fresh archive on a schedule you define.

What the Mastodon Export Contains

The export archive is a tar.gz file that contains CSV files for followers, following, lists, domain blocks, and a JSON file for your outbox of public posts. Media files are not included by default. To back up media, you would need a separate script that downloads each attachment URL from the outbox JSON. This article focuses on the standard export archive.

Prerequisites

Before you begin, you need a machine running Linux or macOS with bash, curl, and jq installed. You also need a Mastodon account with API access enabled. On most instances, API access is enabled by default. You must have write permission to the directory where the backup archive will be saved.

Steps to Schedule a Mastodon Account Export With Cron

Step 1: Create a Mastodon API Token

1. Open your Mastodon preferences
   Click Preferences in the navigation bar, then click Development in the left sidebar.
2. Create a new application
   Click New Application. Enter a name such as Backup Script. Leave all scopes checked. Click Submit.
3. Copy your access token
   After the application is created, you will see a field labeled Your access token. Copy the long string of characters. Store it in a secure location. You will use this token in the backup script.

Step 2: Write the Backup Script

Create a file named mastodon-backup.sh in a directory of your choice, such as /home/username/scripts/. Paste the following content into the file:

#!/bin/bash
# Mastodon account export script
# Replace these variables with your own values
TOKEN="your_access_token_here"
INSTANCE="mastodon.social"
BACKUP_DIR="/home/username/mastodon-backups"

# Create backup directory if it does not exist
mkdir -p "$BACKUP_DIR"

# Generate a timestamp for the filename
TIMESTAMP=$(date +%Y%m%d%H%M%S)

# Request the export archive
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://$INSTANCE/api/v1/exports/archive" \
  -o "$BACKUP_DIR/mastodon-export-$TIMESTAMP.tar.gz"

# Check if the download succeeded
if [ -f "$BACKUP_DIR/mastodon-export-$TIMESTAMP.tar.gz" ]; then
  echo "Backup saved: $BACKUP_DIR/mastodon-export-$TIMESTAMP.tar.gz"
else
  echo "Error: Backup failed"
  exit 1
fi

Step 3: Make the Script Executable and Test It

1. Set execute permission
   Run chmod +x /home/username/scripts/mastodon-backup.sh.
2. Run the script manually
   Execute /home/username/scripts/mastodon-backup.sh from the terminal. Check the backup directory to confirm a tar.gz file was created.
3. Verify the archive contents
   Run tar -tzf /home/username/mastodon-backups/mastodon-export-tar.gz to list the files inside. You should see CSV files and a JSON file.

Step 4: Add the Cron Job

1. Open your user crontab
   Run crontab -e in the terminal. If this is your first time, you may be prompted to choose an editor.
2. Add a cron line
   Insert a new line at the bottom of the file. For a daily backup at 2:00 AM, use:
   0 2 /home/username/scripts/mastodon-backup.sh
   For a weekly backup every Sunday at 2:00 AM, use:
   0 2 0 /home/username/scripts/mastodon-backup.sh
3. Save and exit
   The cron daemon will load the new schedule automatically. You can verify active cron jobs with crontab -l.

Common Mistakes and Limitations

Backup Archive Is Empty or Corrupted

If the downloaded tar.gz file is empty or cannot be extracted, the API token may be invalid or expired. Generate a new token from Preferences > Development and update the script. Also confirm that the instance URL in the script uses https and does not include a trailing slash.

Cron Job Does Not Run

Cron may not have the same environment variables as your interactive shell. If the script uses commands like curl or jq without full paths, cron may fail. Specify the full path to each command in the script. For example, use /usr/bin/curl instead of curl. Run which curl and which jq to find the correct paths on your system.

Disk Space Fills Up Over Time

Each backup archive is typically 100 KB to 1 MB, but over months the files accumulate. Add a cleanup step to the script that deletes archives older than a certain number of days. For example, add find "$BACKUP_DIR" -name "tar.gz" -mtime +30 -delete before the download command to remove files older than 30 days.

Mastodon Export vs Third-Party Backup Tools

Item	Mastodon Export API	Third-Party Tools
Data included	Posts, followers, following, lists, domain blocks	May include media, direct messages, and account settings
Authentication	OAuth token from Preferences > Development	Often requires login credentials or user interaction
Automation	Easy with cron and curl	May require a browser or GUI
Media backup	Not included by default	Some tools download media files separately
Reliability	Official Mastodon API, stable	Depends on the tool and its maintenance

Now you can run the backup script manually whenever you need an immediate export. To extend the automation, add a notification step that sends you a message when the backup completes. For example, you can append a line that uses mail or a webhook to notify you of success or failure. The cron-based approach gives you a reliable, low-maintenance backup routine for your Mastodon account.