Get User History

GET /v1/users/:userId/history

Returns a paginated ledger of all point transactions for a user, including points awarded via events and points spent on games.

Authentication

Header	Required	Value
X-API-Secret	Yes	Your secret key

Path Parameters

Param	Type	Description
userId	string	The user’s external ID

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/users/user_12345/history?page=1&limit=10" \
  -H "X-API-Secret: sk_live_your_secret_key"

JavaScript

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

const response = await fetch(
  `https://api.gamifyhost.com/v1/users/${userId}/history?${params}`,
  {
    method: 'GET',
    headers: {
      'X-API-Secret': 'sk_live_your_secret_key',
    },
  }
);

const data = await response.json();
for (const entry of data.data) {
  console.log(`${entry.eventType}: ${entry.points > 0 ? '+' : ''}${entry.points} pts`);
}

Python

import requests

user_id = "user_12345"

response = requests.get(
    f"https://api.gamifyhost.com/v1/users/{user_id}/history",
    headers={"X-API-Secret": "sk_live_your_secret_key"},
    params={"page": 1, "limit": 10},
)

data = response.json()
for entry in data["data"]:
    sign = "+" if entry["points"] > 0 else ""
    print(f"{entry['eventType']}: {sign}{entry['points']} pts")

Java

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

String userId = "user_12345";

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.gamifyhost.com/v1/users/" + userId + "/history?page=1&limit=10"))
    .header("X-API-Secret", "sk_live_your_secret_key")
    .GET()
    .build();

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

Go

userId := "user_12345"
url := fmt.Sprintf("https://api.gamifyhost.com/v1/users/%s/history?page=1&limit=10", userId)

req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("X-API-Secret", "sk_live_your_secret_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

$userId = 'user_12345';

$ch = curl_init("https://api.gamifyhost.com/v1/users/{$userId}/history?page=1&limit=10");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Secret: sk_live_your_secret_key',
    ],
]);

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

$data = json_decode($response, true);
foreach ($data['data'] as $entry) {
    $sign = $entry['points'] > 0 ? '+' : '';
    echo "{$entry['eventType']}: {$sign}{$entry['points']} pts\n";
}

Ruby

require 'net/http'
require 'json'

user_id = 'user_12345'

uri = URI("https://api.gamifyhost.com/v1/users/#{user_id}/history?page=1&limit=10")
req = Net::HTTP::Get.new(uri)
req['X-API-Secret'] = 'sk_live_your_secret_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|
  sign = entry['points'] > 0 ? '+' : ''
  puts "#{entry['eventType']}: #{sign}#{entry['points']} pts"
end

C#

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

var userId = "user_12345";
var response = await client.GetAsync($"https://api.gamifyhost.com/v1/users/{userId}/history?page=1&limit=10");
var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Dart

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

const userId = 'user_12345';

final response = await http.get(
  Uri.parse('https://api.gamifyhost.com/v1/users/$userId/history?page=1&limit=10'),
  headers: {'X-API-Secret': 'sk_live_your_secret_key'},
);

final data = jsonDecode(response.body);
for (final entry in data['data']) {
  final sign = entry['points'] > 0 ? '+' : '';
  print('${entry['eventType']}: $sign${entry['points']} pts');
}

Response

Status: 200 OK

{
  "message": "User history retrieved",
  "code": 200,
  "status": "success",
  "data": [
    {
      "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "eventType": "signup",
      "points": 500,
      "reference": "ref_signup_user12345",
      "metadata": {
        "source": "ios_app"
      },
      "createdAt": "2025-07-15T10:00:00Z"
    },
    {
      "id": "a9b8c7d6-e5f4-3210-fedc-ba0987654321",
      "eventType": "purchase",
      "points": 100,
      "reference": "order_98765",
      "metadata": {
        "orderId": "98765",
        "amount": 49.99
      },
      "createdAt": "2025-07-15T11:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 12,
    "totalPages": 2
  }
}

Response Fields

Field	Type	Description
id	uuid	Ledger entry ID
eventType	string	Event that triggered the points
points	integer	Points awarded (positive) or spent (negative)
reference	string	Idempotency reference (if provided)
metadata	object	Arbitrary metadata attached to the entry
createdAt	datetime	ISO 8601 timestamp

Errors

Code	Message
404	User not found