Get Leaderboard

GET /v1/leaderboard

Returns the ranked leaderboard with composite scores. Paginated.

Authentication

Header	Required	Value
X-API-Key	Yes	Your public key

Query Parameters

Param	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Results per page

Request Examples

cURL

curl -X GET "https://api.gamifyhost.com/v1/leaderboard?page=1&limit=10" \
  -H "X-API-Key: pk_live_your_public_key"

JavaScript

const params = new URLSearchParams({ page: '1', limit: '10' });

const response = await fetch(
  `https://api.gamifyhost.com/v1/leaderboard?${params}`,
  {
    method: 'GET',
    headers: {
      'X-API-Key': 'pk_live_your_public_key',
    },
  }
);

const data = await response.json();
console.log(data.data);  // Array of ranked entries
console.log(data.meta);  // { page, limit, total, totalPages }

Python

import requests

response = requests.get(
    "https://api.gamifyhost.com/v1/leaderboard",
    headers={"X-API-Key": "pk_live_your_public_key"},
    params={"page": 1, "limit": 10},
)

data = response.json()
for entry in data["data"]:
    print(f"#{entry['rank']} {entry['displayName']} — {entry['score']} pts")

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/leaderboard?page=1&limit=10"))
    .header("X-API-Key", "pk_live_your_public_key")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Go

req, _ := http.NewRequest("GET", "https://api.gamifyhost.com/v1/leaderboard?page=1&limit=10", nil)
req.Header.Set("X-API-Key", "pk_live_your_public_key")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

PHP

$ch = curl_init('https://api.gamifyhost.com/v1/leaderboard?page=1&limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: pk_live_your_public_key',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['data'] as $entry) {
    echo "#{$entry['rank']} {$entry['displayName']} — {$entry['score']} pts\n";
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.gamifyhost.com/v1/leaderboard?page=1&limit=10')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = 'pk_live_your_public_key'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
data['data'].each do |entry|
  puts "##{entry['rank']} #{entry['displayName']} — #{entry['score']} pts"
end

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "pk_live_your_public_key");

var response = await client.GetAsync("https://api.gamifyhost.com/v1/leaderboard?page=1&limit=10");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Dart

import 'dart:convert';
import 'package:http/http.dart' as http;

final response = await http.get(
  Uri.parse('https://api.gamifyhost.com/v1/leaderboard?page=1&limit=10'),
  headers: {'X-API-Key': 'pk_live_your_public_key'},
);

final data = jsonDecode(response.body);
for (final entry in data['data']) {
  print('#${entry['rank']} ${entry['displayName']} — ${entry['score']} pts');
}

Response

Status: 200 OK

{
  "message": "Leaderboard retrieved",
  "code": 200,
  "status": "success",
  "data": [
    {
      "rank": 1,
      "userId": "user_777",
      "displayName": "Alice",
      "totalPoints": 12500,
      "totalRewardsWon": 34,
      "gamesPlayed": 89,
      "score": 14190
    },
    {
      "rank": 2,
      "userId": "user_42",
      "displayName": "Bob",
      "totalPoints": 9800,
      "totalRewardsWon": 22,
      "gamesPlayed": 65,
      "score": 11072
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 156,
    "totalPages": 16
  }
}

Response Fields

Field	Type	Description
rank	integer	Position on the leaderboard
userId	string	User’s external ID
displayName	string	User’s display name
totalPoints	integer	Lifetime points earned
totalRewardsWon	integer	Number of rewards won
gamesPlayed	integer	Total games played
score	integer	Composite score: totalPoints + totalRewardsWon + (gamesPlayed * 10)