The API enables logged in users to more easily query ladder data.

Currently the API exposes data as it is structured within the database.

The API uses the Django Rest Framework:


You need to be logged in to view the API via the website. If you are, endpoints are listed here:
To get an API token go here.

List data objects -
Get a list of matches:

Get specific item
Get match ID 4567:

Get all active users:
Search for users with "lad" in one of their fields:

Get most recent results first:

Example scenarios:

Download all of a bot's replays:

  1. Obtain the bot's id from
  2. Get a list of all the bot's participations in matches:
  3. For each match id in the participants list:
        Get the result for that match:
        Download the replay using the URL in the replay_file field

Use Python to download the bot's latest 100 replays

  1. Obtain your API Token here
  2. Follow the above steps to get the bot's id
  3. Execute the following (after inputting necessary values):
import json
import os

import requests

# Download
bot_id = 0  # insert bot id
token = ''  # insert token you received from admin
file_path = './replays/'  # insert file path
auth = {'Authorization': f'Token {token}'}

# requests.get(url).text returns a dictionary formatted as a string and we need dictionaries
response = requests.get(f'{bot_id}', headers=auth)
assert response.status_code == 200, 'Unexpected status_code returned from match-participations'
participation = json.loads(response.text)
for i in range(len(participation['results'])):
    print(f'Downloading match {participation["results"][i]["match"]}')
    response = requests.get(f'{participation["results"][i]["match"]}', headers=auth)
    assert response.status_code == 200, 'Unexpected status_code returned from results'
    match_details = json.loads(response.text)
    replay_file = match_details['results'][0]['replay_file']
    if replay_file not in (None, 'null'):
        replay = requests.get(replay_file, headers=auth)
        with open(os.path.join(file_path, str(participation["results"][i]["match"])+'.SC2Replay'), 'wb') as f:

Get the top 10 active bots ranked by ELO

Order by elo descending, and limit the page to 10 entries: