Stats API Docsv1

Data endpoints for player bots and tools.

Get Started

Authentication

  • An API key is required for all requests
  • Create a key from Account Settings on the website
  • Strictly, one key per person
  • Using multiple keys will result in all access being revoked
  • Key creation is currently limited. If you are not eligible but would like to request access, contact the Admin on Discord

Rate limits

  • 30 requests per minute (500 per hour)
  • Some endpoints may also list their own limit below
  • 2x usage for supporters
  • Higher usage can be requested by contacting the Admin on Discord

Request example

1

Set your API key

Set your key as an environment variable. The commands below read it from DREAM_API_KEY, so it never lands in your shell history or source.

export DREAM_API_KEY="YOUR_API_KEY"
2

Make your first API call

Send a GET request to /api/v1/usage.php. Choose how to send the key, then your language:

cURL
curl https://dreamms.gg/api/v1/usage.php \
  -H "X-API-Key: $DREAM_API_KEY"
cURL
curl https://dreamms.gg/api/v1/usage.php \
  -H "Authorization: Bearer $DREAM_API_KEY"
cURL
curl "https://dreamms.gg/api/v1/usage.php?key=$DREAM_API_KEY"
Python
import os
import requests

res = requests.get(
    "https://dreamms.gg/api/v1/usage.php",
    headers={"X-API-Key": os.environ["DREAM_API_KEY"]},
)
print(res.json())
Python
import os
import requests

res = requests.get(
    "https://dreamms.gg/api/v1/usage.php",
    headers={"Authorization": f"Bearer {os.environ['DREAM_API_KEY']}"},
)
print(res.json())
Python
import os
import requests

res = requests.get(
    "https://dreamms.gg/api/v1/usage.php",
    params={"key": os.environ["DREAM_API_KEY"]},
)
print(res.json())
JavaScript / TypeScript
const res = await fetch("https://dreamms.gg/api/v1/usage.php", {
  headers: { "X-API-Key": process.env.DREAM_API_KEY },
});
const data = await res.json();
console.log(data);
JavaScript / TypeScript
const res = await fetch("https://dreamms.gg/api/v1/usage.php", {
  headers: { "Authorization": "Bearer " + process.env.DREAM_API_KEY },
});
const data = await res.json();
console.log(data);
JavaScript / TypeScript
const res = await fetch("https://dreamms.gg/api/v1/usage.php?key=" + process.env.DREAM_API_KEY);
const data = await res.json();
console.log(data);
3

Read the response

Every response is returned in JSON. A successful call looks like:

Output
{
  "ok": true,
  "data": {
    "rate": 1,
    "global": {
      "perMinute": { "limit": 30, "used": 2, "remaining": 28, "window": 60, "reset": 41 },
      "perHour": { "limit": 500, "used": 17, "remaining": 483, "window": 3600, "reset": 2873 }
    },
    "endpoints": {
      "player": { "limit": 10, "used": 1, "remaining": 9, "window": 60, "reset": 41 },
      "economy": { "limit": 5, "used": 0, "remaining": 5, "window": 60, "reset": 0 }
    }
  },
  "meta": { "cachedAt": "2026-06-29T12:00:00+00:00" }
}

Endpoints

GET /api/v1/usage.php rate global limit only cache never

Your current rate-limit usage: used/remaining per window and seconds until each resets.

Example: https://dreamms.gg/api/v1/usage.php

GET /api/v1/economy.php rate 5/min cache 3600s

Average price and total sold of verified trades and merchant sales over a period.

paramdefaultdescription
item * — exact item name (case in-sensitive), eg. "white scroll"
period 30 7 | 14 | 30 | 90 | 180 | all

Example: https://dreamms.gg/api/v1/economy.php?item=White%20Scroll&period=30

GET /api/v1/player.php rate 10/min cache 120s

Player profiles. Search up to 18 players separated by commas.

paramdefaultdescription
name * — exact name(s), up to 18 comma-separated, case-insensitive

Example: https://dreamms.gg/api/v1/player.php?name=Issue,misaki,glidestep

GET /api/v1/rankings.php rate global limit only cache 300s

Rankings. Up to 50 rows per request. Only the top 1000 may be requested.

paramdefaultdescription
type overall overall | job | dpm | mdpm | fame
job — job id, required when type=job (e.g. 412 = Night Lord)
page 1 page number; rejected once rank reaches 1000
limit 25 rows per page, max 50

Example: https://dreamms.gg/api/v1/rankings.php?type=job&job=412

Job IDs (85)
0 Beginner
100 Warrior
110 Fighter
111 Crusader
112 Hero
120 Page
121 White Knight
122 Paladin
130 Spearman
131 Dragon Knight
132 Dark Knight
200 Magician
210 F/P Wizard
211 F/P Mage
212 F/P Arch Mage
220 I/L Wizard
221 I/L Mage
222 I/L Arch Mage
230 Cleric
231 Priest
232 Bishop
300 Archer
310 Hunter
311 Ranger
312 Bow Master
320 Crossbowman
321 Sniper
322 Marksman
400 Thief
410 Assassin
411 Hermit
412 Night Lord
420 Bandit
421 Chief Bandit
422 Shadower
430 Blade Recruit
431 Blade Acolyte
432 Blade Specialist
433 Blade Lord
434 Blade Master
500 Pirate
510 Brawler
511 Marauder
512 Buccaneer
520 Gunslinger
521 Outlaw
522 Corsair
910 Game Master
1000 Noblesse
1100 Dawn Warrior
1110 Dawn Warrior
1111 Dawn Warrior
1112 Dawn Warrior
1200 Blaze Wizard
1210 Blaze Wizard
1211 Blaze Wizard
1212 Blaze Wizard
1300 Wind Archer
1310 Wind Archer
1311 Wind Archer
1312 Wind Archer
1400 Night Walker
1410 Night Walker
1411 Night Walker
1412 Night Walker
1500 Thunder Breaker
1510 Thunder Breaker
1511 Thunder Breaker
1512 Thunder Breaker
2000 Legend
2001 Evan
2100 Aran
2110 Aran
2111 Aran
2112 Aran
2200 Evan
2210 Evan
2211 Evan
2212 Evan
2213 Evan
2214 Evan
2215 Evan
2216 Evan
2217 Evan
2218 Evan
GET /api/v1/expeditions.php rate global limit only cache 21600s

Expedition leaderboards: total completions, top classes, fastest run times, top player records.

paramdefaultdescription
range all 24h | 7d | 30d | 90d | all
type — completions | classes | fastest | records

Example: https://dreamms.gg/api/v1/expeditions.php?range=30d&type=fastest

GET /api/v1/event.php rate global limit only cache 300s

Real-time event leaderboards. Displays unique players.

paramdefaultdescription
event * — event id (see Event IDs)
type jq jq

Example: https://dreamms.gg/api/v1/event.php?event=5thanni&type=jq

Event IDs (1)
5thanni 5th Anniversary Event
GET /api/v1/population.php rate global limit only cache 60s

Real-time online and peak count; total/unique players active players.

Example: https://dreamms.gg/api/v1/population.php

GET /api/v1/changelog.php rate global limit only cache 1800s

The most recent changelogs.

paramdefaultdescription
count 5 number of entries, max 20
format html html | text

Example: https://dreamms.gg/api/v1/changelog.php?count=3&format=text

Error codes

HTTPcode · meaning
400bad_request - a parameter was missing or invalid
404not_found - no matching record
401unauthorized - a valid ?key= is required
405method_not_allowed - use GET or HEAD
429rate_limited - slow down (see Retry-After)
503unavailable - backend temporarily down

Stats API v1 · Made with ❤️ by Dream MS