How to Build a Mastodon Export Backup to S3 Bucket Automatically

Mastodon stores your account data, including posts, media, and followers, on the server you joined. If you lose access to that server or it shuts down, your data can disappear. A manual export through the Mastodon web interface creates a backup archive, but you must download it each time and store it locally. This article explains how to automate that export process and send the archive directly to an Amazon S3 bucket using a simple script and a scheduled task.

The automation uses the Mastodon API to trigger an export and a command-line tool to upload the resulting file to S3. You do not need advanced programming skills. You only need a Mastodon access token, an AWS account with an S3 bucket, and a system that can run a script on a schedule. After setup, your backup runs without manual intervention.

This guide covers the full process: generating a Mastodon API token, creating a Python script to fetch the export, installing the AWS CLI for the upload, and scheduling the script on Windows or Linux. You will also learn how to handle common errors such as expired tokens or failed uploads.

How Mastodon Export Automation Works

Mastodon provides a REST API endpoint that triggers a full account export. The export includes your toots, media attachments, lists, bookmarks, and follower data. The server generates a zip file and returns a download URL. You must authenticate with an access token that has the read scope.

The automation script sends a POST request to the export endpoint, waits for the archive to be generated, and then downloads the file. After the download completes, the script calls the AWS CLI to copy the file to your S3 bucket. The script also handles cleanup by deleting the local archive after a successful upload.

Prerequisites

Before writing the script, prepare the following:

• A Mastodon account on any instance. The instance must support API access, which most public instances do.
• An AWS account with an S3 bucket. The bucket must have write permissions for the IAM user or role you use.
• AWS CLI installed and configured on the machine that will run the script. Run aws configure to set your access key, secret key, and region.
• Python 3.6 or newer with the requests library installed. Install it with pip install requests.

Steps to Build the Automatic Backup Script

Step 1: Generate a Mastodon API Access Token

1. Open your Mastodon account settings
   Click the gear icon in the Mastodon web interface and select Preferences.
2. Navigate to Development
   In the left sidebar, click Development.
3. Create a new application
   Click the New Application button.
4. Configure the application
   Enter a name such as “Auto Backup Script.” Under Scopes, select only read. Do not select write or follow scopes.
5. Submit and copy the token
   Click Submit. On the next page, copy the Your access token value. Store it securely. You will add it to the script later.

Step 2: Write the Python Backup Script

Create a new file named mastodon_backup.py and paste the following code. Replace the placeholder values with your own.

import requests
import os
import subprocess
from datetime import datetime

# Configuration
MASTODON_INSTANCE = "https://your-instance.example"  # Replace with your instance URL
ACCESS_TOKEN = "your_access_token_here"               # Replace with your token
S3_BUCKET = "s3://your-bucket-name/backups/"          # Replace with your bucket path
LOCAL_DIR = "/tmp/mastodon_backup"                    # Temp directory for download

# Create temp directory if it does not exist
os.makedirs(LOCAL_DIR, exist_ok=True)

# Step 1: Request export
export_url = f"{MASTODON_INSTANCE}/api/v1/exports"
headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}
response = requests.post(export_url, headers=headers)

if response.status_code != 200:
    print(f"Failed to request export: {response.status_code}")
    exit(1)

data = response.json()
export_id = data.get("id")
status_url = f"{MASTODON_INSTANCE}/api/v1/exports/{export_id}"

# Step 2: Poll until export is ready
import time
while True:
    status_response = requests.get(status_url, headers=headers)
    if status_response.status_code != 200:
        print(f"Failed to check export status: {status_response.status_code}")
        exit(1)
    status_data = status_response.json()
    if status_data.get("processed"):
        download_url = status_data.get("url")
        break
    time.sleep(10)

# Step 3: Download the archive
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
local_file = os.path.join(LOCAL_DIR, f"mastodon_export_{timestamp}.zip")
print(f"Downloading export to {local_file}")
download_response = requests.get(download_url, headers=headers)
with open(local_file, "wb") as f:
    f.write(download_response.content)

# Step 4: Upload to S3
print(f"Uploading to {S3_BUCKET}")
result = subprocess.run(["aws", "s3", "cp", local_file, S3_BUCKET], capture_output=True, text=True)
if result.returncode != 0:
    print(f"Upload failed: {result.stderr}")
    exit(1)

# Step 5: Clean up local file
os.remove(local_file)
print("Backup completed successfully")

Step 3: Test the Script Manually

1. Open a terminal or command prompt
   Navigate to the directory containing mastodon_backup.py.
2. Run the script
   Execute python mastodon_backup.py. The script will request the export, download it, and upload it to S3. Check the console output for errors.
3. Verify the upload
   Log in to the AWS Management Console, open your S3 bucket, and confirm the zip file appears in the backups/ folder.

Step 4: Schedule the Script to Run Automatically

Choose the scheduling method for your operating system.

Windows: Task Scheduler

1. Open Task Scheduler
   Press Win+R, type taskschd.msc, and press Enter.
2. Create a new task
   Click Create Task in the Actions pane. Give it a name like “Mastodon Backup.”
3. Set the trigger
   Go to the Triggers tab and click New. Set the frequency to weekly or monthly. Click OK.
4. Set the action
   Go to the Actions tab and click New. Set Action to Start a program. In Program/script, enter the full path to python.exe. In Add arguments, enter the full path to mastodon_backup.py. Click OK.
5. Configure conditions
   Uncheck Start the task only if the computer is on AC power if you want it to run on battery. Click OK to save.

Linux: cron

1. Open the crontab editor
   Run crontab -e in the terminal.
2. Add a cron line
   Add the following line to run the script every Sunday at 3 AM:
   0 3 0 /usr/bin/python3 /home/username/mastodon_backup.py
3. Save and exit
   cron will automatically enable the job.

Common Issues and How to Fix Them

Mastodon API Returns 401 Unauthorized

The access token is incorrect or expired. Regenerate a new token in Preferences > Development. Ensure the token has the read scope. Copy the new token into the script.

Export Request Returns 422 Unprocessable Entity

Your Mastodon account may have too many pending exports. Wait 15 minutes and try again. The server limits how often you can request a full export. If the error persists, check the instance’s API rate limit documentation.

AWS CLI Upload Fails with Access Denied

The IAM user or role used by the AWS CLI does not have permission to write to the S3 bucket. Attach the AmazonS3FullAccess policy to the IAM user, or use a more restrictive policy that includes s3:PutObject on the bucket ARN.

Script Runs but No File Appears in S3

Check the console output for error messages. The script may have failed during the download or upload step. Run the script manually with python mastodon_backup.py to see the full output. Verify that the AWS CLI is configured with the correct region and credentials.

Manual Export vs Automated S3 Backup: Key Differences

Item	Manual Export via Web UI	Automated S3 Backup Script
Trigger method	Click a button in Preferences > Export	API request from a scheduled script
Storage location	Local computer download folder	Amazon S3 bucket (cloud)
Frequency	Must be done manually each time	Runs on a schedule (cron or Task Scheduler)
File retention	Depends on user’s local backup habits	Automatically kept in S3 with versioning if enabled
Security	File stored on local disk, no encryption at rest by default	S3 supports server-side encryption (SSE-S3 or SSE-KMS)

You now have a fully automated system that exports your Mastodon data and stores it securely in Amazon S3. The script runs on a schedule you define, so you never need to remember to back up manually. For extra protection, enable S3 versioning on your bucket to retain multiple backup copies. If you run multiple Mastodon accounts, modify the script to loop through each account’s token and bucket path.