Leaderboard

Fetch a ranked leaderboard for any contest. Viral and referral campaigns rank by points; affiliate campaigns rank by commission earned.

Get Leaderboard

GET/api/v1/contests/:contestId/leaderboard

Public or Private API Key

Returns a ranked list of contest entries. Only confirmed, non-disqualified entries are included.

Viral / referral campaigns: ordered by points descending
Affiliate campaigns: ordered by commission (totalCommissionEarned) descending

The response includes a top-level metric field ("points" or "commission") indicating which value drives ranking.

Path Parameters

contestIdstring required

The unique contest identifier

Query Parameters

limitnumber optional

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

Request

bash

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

javascript

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`);
});

python

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

json

{
  "success": true,
  "metric": "points",
  "data": [
    {
      "rank": 1,
      "id": "entry_abc123",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "points": 350,
      "commission": 0,
      "referralCode": "REF-XYZ789",
      "referralsCount": 12,
      "joinedAt": "2025-06-01T10:00:00.000Z"
    },
    {
      "rank": 2,
      "id": "entry_def456",
      "email": "john@example.com",
      "name": "John Smith",
      "points": 280,
      "referralCode": "REF-ABC456",
      "referralsCount": 8,
      "joinedAt": "2025-06-02T14:30:00.000Z"
    },
    {
      "rank": 3,
      "id": "entry_ghi789",
      "email": "alex@example.com",
      "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

commissionnumber

Total commission earned in dollars (affiliate campaigns)

metricstring

Ranking metric for this contest: points or commission

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 ordered by points or commission depending on campaign mode
The limit parameter accepts values between 1 and 100
Use this endpoint with a public key to build client-side leaderboard widgets

javascript

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

Common error responses for this endpoint.

Status	Error	Description
`400`	Missing contestId	The contestId path parameter is required
`401`	Invalid API key	API key is missing or invalid
`404`	Contest not found	No contest exists with the given ID