> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Leaderboard

> Global, weekly, monthly, and category-based leaderboard rankings.

# Leaderboard

LearnWay tracks competitive learner rankings based on accumulated XP, quiz battle scores, and streaks.

***

## Weekly Leaderboard

Returns the current active week's ranked standings.

### Endpoint

```http theme={null}
GET /api/v2/leaderboard/weekly
```

### Query Parameters

| Parameter | Type     | Required | Description                                  |
| :-------- | :------- | :------- | :------------------------------------------- |
| `limit`   | `number` | No       | Number of entries to return (default: `100`) |
| `offset`  | `number` | No       | Offset for pagination (default: `0`)         |

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "period": "week",
    "startDate": "2026-08-17T00:00:00.000Z",
    "endDate": "2026-08-23T23:59:59.999Z",
    "entries": [
      {
        "rank": 1,
        "userId": "user-uuid-1",
        "username": "cryptosage",
        "avatarUrl": "https://ik.imagekit.io/learnway/avatars/1.png",
        "totalXP": 3450,
        "totalGems": 280,
        "currentStreak": 14
      },
      {
        "rank": 2,
        "userId": "user-uuid-2",
        "username": "alice_builder",
        "avatarUrl": "https://ik.imagekit.io/learnway/avatars/2.png",
        "totalXP": 3120,
        "totalGems": 240,
        "currentStreak": 9
      }
    ]
  },
  "message": "Weekly leaderboard retrieved successfully"
}
```

***

## Monthly & All-Time Leaderboards

* `GET /api/v2/leaderboard/monthly` – Monthly leaderboard standings.
* `GET /api/v2/leaderboard/all-time` – Global all-time leaderboard rankings.