Ranking | Leaderboards API Reference

POST /api/leaderboards/ranking.php

Authorization: AppID:AppKey or user session token

Identify the leaderboard (one of)

Field	Type	Description
leaderboard_id	int	Numeric leaderboard ID
slug + app_id	string	Slug and app package name together

Options

Field	Type	Description
scope	string	`global` (default) or `friends`
limit	int	Entries to return (1–100). Default: `50`
offset	int	Skip first N entries for pagination (global scope only)

Friends scope — identify user (when auth is AppID:AppKey — one of)

Field	Type	Description
user_id	int	Numeric user ID
userkey	string	User's `userKey`
token	string	User's session token

When authenticated with a user token in the header, scope=friends and my_position work without extra body fields.

Test this endpoint

Headers

Authorization *

Body

slug

app_id

scope

limit

offset

Success response 200

{
  "success": true,
  "leaderboard": {
    "id": 1,
    "slug": "goals",
    "name": "Top Scorers",
    "points_name": "Goals",
    "sort_order": "desc"
  },
  "scope": "global",
  "count": 3,
  "entries": [
    {
      "rank": 1,
      "id": 10,
      "username": "champion",
      "name": "Champion",
      "profileimg": "https://...",
      "idverify": 1,
      "score": 87,
      "updated_at": "2026-05-29 16:00:00"
    },
    {
      "rank": 2,
      "id": 42,
      "username": "vanelton",
      "score": 47,
      "updated_at": "2026-05-29 15:00:00"
    }
  ],
  "my_position": {
    "rank": 2,
    "score": 47,
    "updated_at": "2026-05-29 15:00:00",
    "leaderboard_id": 1
  }
}

my_position is always the user's global rank regardless of the requested scope, so you can show "Your global rank: #2" even when displaying a friends-only board. It is null when authenticated with AppID:AppKey without a user identifier.

Pagination

// Page 1
{ "slug": "goals", "app_id": "com.myapp.game", "limit": 20, "offset": 0 }   // ranks 1–20
// Page 2
{ "slug": "goals", "app_id": "com.myapp.game", "limit": 20, "offset": 20 }  // ranks 21–40