Docs Migration & Backups

Documentation

Backup & Migration Guide

Export, back up, and restore your Team Up leaderboards — or transfer them to a new Discord server

Jump to Section

📋 Overview 💾 Backup & Restore 🔁 Transfer Servers

Overview

Team Up lets you export any leaderboard to a JSON file and re-import it later — for backups, disaster recovery, or moving a community to a new server.

Import Options

/backup import - Restore from a Team Up export file

Export Options

/backup export - Export leaderboard as JSON
Includes ratings, match history, and profiles

Rate Limits

Free Tier

5 exports per day
2 imports per day
1 MB max file size
100 history records

Pro Tier

100 exports per day
50 imports per day
20 MB max file size
5,000 history records

Unlimited removes all four caps. "History records" is the plan ceiling, not what a single export pulls — /backup export asks for the 1,000 most recent matches, so Pro and Unlimited both export up to 1,000 per leaderboard and the plan limit is what trims Free to 100.

Backup & Restore (Team Up Format)

Export Your Leaderboard

Create a complete backup of your leaderboard data including ratings, match history, and profiles.

/backup export leaderboard:"default"

Downloads a JSON file for that one leaderboard, carrying its 1,000 most recent matches. The leaderboard option autocompletes; run the command once per leaderboard.

Team Up Export Format

The exported file contains comprehensive leaderboard data:

{
  "leaderboard_info": {
    "leaderboard": "default",
    "display_name": "Default Leaderboard",
    "elo_default_rating": 1200,
    "matches_required_for_ranking": 0
  },
  "ratings": [
    {
      "id": "DISCORD|123|player_global_even|default|987654321098765432",
      "rating_group": "DISCORD|123|player_global_even|default",
      "team": ["987654321098765432"],
      "elo": 1450,
      "matches": 25,
      "rating_type": "player_global_even",
      "leaderboard": "default"
    }
  ],
  "history": [...],
  "playerHistory": [...],
  "teamHistory": [...],
  "profiles": {
    "players": [...],
    "teams": [...],
    "client": { ... }
  },
  "ratingTypes": [...]
}

Restore from Backup

Import a Team Up export file to restore or transfer leaderboard data.

/backup import data_file:[attach your .json file] leaderboard:"default"

Creates the leaderboard and restores its ratings, history and profiles. The name must be one the server does not already have.

Important Notes

An import creates the leaderboard. If one with that name already exists it stops with Leaderboard 'name' already exists and writes nothing — imports never merge into, update, or overwrite an existing leaderboard.
To re-import into a name that is taken, export it first, then delete it with /danger_zone delete_leaderboard, then import.
Ratings, match counts and the leaderboard's Elo settings come across as-is. Win/loss records, streaks and best/worst Elo are not in the file — rebuild them with Recompute Elo Ratings on the dashboard.
Server admin permissions are required for backup commands

Transferring to a New Server

Moving your community to a new Discord server is one export/import per leaderboard, plus a few things the backup file does not carry.

Move your premium time first

Both the export and the import trim match history to the plan of the server they run on, so importing into a server with no subscription silently truncates every leaderboard to its 100 most recent matches and caps the file at 1 MB. Move the subscription across before you import and nothing is trimmed.

1. Add Team Up to the new server

Invite the bot and make sure you have admin permissions.

2. Move the subscription

Add the new server as a league on the dashboard. Open the old league → Settings and move its premium time from the Discord side to the web side, then open Premium and transfer that time to the new league.

3. Export from the old server

/backup export leaderboard:"ranked"

Once per leaderboard.

4. Import into the new server

/backup import data_file:[your file] leaderboard:"ranked"

Into a name the new server does not already have.

5. Rebuild what the file doesn't carry

On the dashboard, open the new league → Rankings → the leaderboard → Danger Zone and run Recompute Elo Ratings (win/loss records, streaks, best and worst Elo, placement counts), Recompute Head-to-Head (player-vs-player and team-vs-team records — these aren't in the export at all), and Recompute Stat Aggregates (custom-stat totals).

In the backup file

Elo settings — K-factor, default rating, provisional, Streak Boost, tier definitions, colors
Every rating, with its match count
Match history, and each player's and team's own match records
Player and team profiles, and rating types

Set up again in the new server

Matchmaking queues
Channel mappings, leaderboard display messages, tier-notification channel
The server's default leaderboard
Webhooks, choice sets, challenge config, audit config, featured ratings
Tier roles — the tier definitions come across, but they carry role IDs from the old server

Note on User IDs

Discord user IDs are the same in every server, so ratings land on the right people. Players who aren't in the new server keep their ratings, but won't appear with updated names until they join.

Troubleshooting

"File is too large"

The file exceeds your tier's size limit.

Free tier: 1 MB max
Pro tier: 20 MB max
Consider splitting large exports into multiple leaderboards

"Invalid JSON file format"

The file isn't valid JSON or doesn't match the expected structure.

Verify the file is valid JSON (use a JSON validator)
Ensure the file matches the Team Up export format
Check that player IDs are valid Discord snowflakes (17-19 digit numbers)
Ensure all required fields are present

"Leaderboard already exists"

The import target has to be a leaderboard that does not exist yet — imports create a leaderboard, they never merge into one.

Import under a name the server doesn't have
Or export the existing leaderboard, delete it with /danger_zone delete_leaderboard, then import

"Rate limit exceeded"

You've reached your daily import/export limit.

Wait for the rate limit to reset (shown in the error message)
Upgrade to Pro tier for higher limits
Plan your imports/exports in advance

"Failed to download file"

Discord's file URL may have expired or is inaccessible.

Try running the command again with a fresh file upload
Ensure the file is attached directly to the command message
Check that the file hasn't been deleted from Discord

Continue Your Setup

Now that your data is backed up, explore more features

📚