Leaderboard

Retrieve ranked participant leaderboards

On this page

Leaderboard

Fetch a ranked leaderboard for any contest, showing top participants ordered by points.

Get Leaderboard

GET/api/v1/contests/:contestId/leaderboard
Public or Private API Key

Returns a ranked list of contest entries ordered by points (highest first). Only confirmed, non-disqualified entries are included.

Path Parameters

contestIdstring required

The unique contest identifier

Query Parameters

limitnumber

Number of entries to return (1-100). Default: 25

Request

curl -X GET "https://blitzrocket.com/api/v1/contests/clx1abc123/leaderboard?limit=10" \
  -H "x-api-key: your_api_key_here"

const contestId = "clx1abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/contests/${contestId}/leaderboard?limit=10`,
  {
    headers: { "x-api-key": "your_api_key_here" },
  }
);

const { data } = await response.json();
data.forEach((entry) => {
  console.log(`#${entry.rank} ${entry.name || entry.email}: ${entry.points} pts`);
});

import requests

contest_id = "clx1abc123"
response = requests.get(
    f"https://blitzrocket.com/api/v1/contests/{contest_id}/leaderboard",
    headers={"x-api-key": "your_api_key_here"},
    params={"limit": 10}
)

data = response.json()["data"]
for entry in data:
    name = entry.get("name") or entry["email"]
    print(f"#{entry['rank']} {name}: {entry['points']} pts")

Response

{
  "success": true,
  "data": [
    {
      "rank": 1,
      "id": "entry_abc123",
      "email": "[email protected]",
      "name": "Jane Doe",
      "points": 350,
      "referralCode": "REF-XYZ789",
      "referralsCount": 12,
      "joinedAt": "2025-06-01T10:00:00.000Z"
    },
    {
      "rank": 2,
      "id": "entry_def456",
      "email": "[email protected]",
      "name": "John Smith",
      "points": 280,
      "referralCode": "REF-ABC456",
      "referralsCount": 8,
      "joinedAt": "2025-06-02T14:30:00.000Z"
    },
    {
      "rank": 3,
      "id": "entry_ghi789",
      "email": "[email protected]",
      "name": null,
      "points": 195,
      "referralCode": "REF-DEF123",
      "referralsCount": 3,
      "joinedAt": "2025-06-03T09:15:00.000Z"
    }
  ]
}

Response Fields

ranknumber

Position in the leaderboard (1-based)

idstring

Unique entry identifier

emailstring

Participant email address

namestring | null

Participant name

pointsnumber

Total points earned

referralCodestring | null

Participant's referral code

referralsCountnumber

Number of successful referrals

joinedAtstring

ISO 8601 timestamp when the participant joined

Usage Notes

  • Only returns entries where emailConfirmed is true and disqualified is false
  • Results are always ordered by points descending
  • The limit parameter accepts values between 1 and 100
  • Use this endpoint with a public key to build client-side leaderboard widgets

Example: Leaderboard Widget

async function renderLeaderboard(contestId, container) {
  const response = await fetch(
    `https://blitzrocket.com/api/v1/contests/${contestId}/leaderboard?limit=10`,
    {
      headers: { "x-api-key": "your_public_key_here" },
    }
  );

  const { data } = await response.json();

  container.innerHTML = data
    .map(
      (entry) => `
      <div class="leaderboard-entry">
        <span class="rank">#${entry.rank}</span>
        <span class="name">${entry.name || "Anonymous"}</span>
        <span class="points">${entry.points} pts</span>
        <span class="referrals">${entry.referralsCount} referrals</span>
      </div>
    `
    )
    .join("");
}

Error Responses

StatusErrorDescription
400Missing contestIdThe contestId path parameter is required
401Invalid API keyAPI key is missing or invalid
404Contest not foundNo contest exists with the given ID