Public API reference for xb.live / Insignia Stats. Most routes are anonymous; a few require a valid Insignia session (noted per endpoint).
All endpoints are relative to your site (e.g. https://insigniastats.live).
4d530064) or game name (URL-encoded where used in paths). Title IDs are stable identifiers across the platform.
Insignia Stats uses a separate auth service for login. To sign in on the website, use the Login page. Your account and password are managed by the Insignia auth service; the stats site does not store your password.
For integrating login into your own pages or apps, include the client SDK and use the InsigniaAuth class. The SDK persists the session in localStorage and exposes login, logout, and user data methods.
<script src="https://insigniastats.live/insignia-auth.js"></script>Constructor:
| Option | Description |
|---|---|
| apiUrl | Auth API base URL (default: https://auth.insigniastats.live/api) |
| storageKey | localStorage key for session (default: insignia_auth) |
| Method | Description |
|---|---|
| login(email, password) | Log in; returns { success, user, sessionKey }. Emits login event. |
| logout() | Log out and clear session. Emits logout event. |
| getUser() | Returns current user { username, email } or null. |
| isLoggedIn() | Returns true if a session key exists (does not verify server-side). |
| verifySession() | Verifies the session with the auth server; returns boolean. |
| getFriends() | Returns cached friends: { friends: [{ gamertag, status, isOnline, game?, duration?, lastSeen? }], lastUpdated, count }. When online: game, duration; when offline: lastSeen. |
| getGames() | Returns cached My Games Played: { games: [{ title, lastPlayed, iconUrl }], lastUpdated, count }. lastPlayed is e.g. "10 minutes ago". |
| getProfile() | Returns cached profile: { isOnline, status, game?, timeOnline?, gamesPlayed: [{ title, lastPlayed, iconUrl }], lastUpdated, count }. |
| refreshFriends() | Refreshes friends from Insignia; returns updated friends data. |
| refreshGames() | Refreshes games (from profile My Games Played); returns updated games data. |
| refreshProfile() | Refreshes profile from Insignia; returns updated profile. |
| getMutes() | Deprecated. Mutes no longer available from Insignia; returns empty list. |
| startAutoVerify(intervalMs) | Periodically re-verifies the session (e.g. every 5 minutes). |
on('login', fn), on('logout', fn), on('error', fn).
const auth = new InsigniaAuth({ apiUrl: 'https://auth.insigniastats.live/api' });
if (auth.isLoggedIn()) {
const user = await auth.getUser();
console.log('Logged in as', user.username);
} else {
await auth.login(email, password);
}
Per-user profile data for the site. :username is the Insignia site username (URL-encode when needed). These GET routes are public.
{
"username": "PlayerOne",
"profile": {
"avatar_url": "...",
"discord_profile_url": "...",
"display_name_override": null,
"linked_gamertag": "...",
"xbox_verified": false,
"bio": "...",
"social_links": []
},
"playTime": { "totalMinutes": 0, "lastState": "offline", "currentGame": null, ... },
"achievementScore": 1200,
"achievementCount": 5,
"newUnlocks": [],
"leaderboardPlayerName": "GamertagOrUsername",
"leaderboardStats": { "leaderboardsOn": 0, "top10Count": 0 },
"usesExplicitXboxLiveGamertag": false
}
{
"score": 1200,
"achievements": [ ... ],
"groups": [ ... ]
}
{
"games": [ ... ],
"leaderboardSupplement": false,
"hasPlayTimeTracking": true
}
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 10 | Max entries (1–50) |
{
"playerName": "...",
"explicitXboxLiveGamertag": null,
"usingSiteUsernameFallback": true,
"scores": [ ... ]
}
Changing bio, avatar, linked gamertag, etc. requires a valid Insignia session. Send X-Session-Key as a header, or sessionKey in the JSON body.
avatar_url, avatar_hue, discord_profile_url, display_name_override, linked_gamertag, bio, sync_avatar_from_discord. Optional social_links (normalized list) when Discord is linked per server rules. Discord URL changes may trigger avatar/name sync from Discord.400 — missing sessionKey, invalid social links, or bad Discord URL; 401 — invalid session; 403 — social links without verified Discord; 502 — Discord lookup failure in some cases.
Star ratings and optional comments left on user profiles. The displayed average uses a Bayesian-style prior (equivalent to 10 ratings at 5★) so new profiles stay near 5 until real feedback arrives.
viewer contains their stars/comment (omit X-Session-Key for anonymous).| Parameter | Type | Default | Description |
|---|---|---|---|
| feedbackLimit | integer | 12 | Recent feedback rows (max 30) |
Optional session: header X-Session-Key or query sessionKey — used only to populate viewer when the signed-in user has already submitted feedback.
{
"average": 4.85,
"ratingCount": 3,
"effectiveVotes": 13,
"priorOnly": false,
"feedback": [
{ "raterUsername": "...", "stars": 5, "comment": null, "createdAt": "..." }
],
"viewer": null
}
When signed in and you have rated this profile, viewer is an object with stars, comment, createdAt; otherwise null.
| Field | Type | Description |
|---|---|---|
| sessionKey | string | Required unless using X-Session-Key header |
| stars | integer | 1–5 |
| comment | string | Optional; trimmed, max 500 characters |
400 — missing session key, invalid username, self-rating, or invalid stars; 401 — invalid session.
{
"success": true,
"reputation": { "average": 4.9, "ratingCount": 4, ... },
"viewer": { "stars": 5, "comment": null, "createdAt": "..." }
}
Site-wide achievement catalog and leaderboards (points total and recent unlocks).
is_hidden; the public catalog never exposes revealed_name / revealed_description (those appear only on a profile after the user unlocks the achievement).{
"achievements": [ ... ],
"groups": [ ... ],
"stats": {
"maxGamerscore": 12345,
"totalAchievements": 400,
"playersWithAchievements": 1200
}
}
| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 25 | Max rows (1–100) |
{ "leaderboard": [ { "rank": 1, "username": "...", "totalScore": 1200, "achievementCount": 5 } ] }
achievementName includes the game label (e.g. Insignia Tourist — XBL Core or Be a WORM — Worms 4: Mayhem). Hidden achievements use the title Hidden Achievement with no spoiler details (no spoiler).| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 10 | Max rows (1–100) |
{ "recent": [ { "username": "...", "unlockedAt": "...", "achievementId": 1, "achievementKey": "...", "achievementName": "...", "gameName": "...", "points": 10 } ] }
Site-wide stats scraped from the Insignia.live homepage.
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | integer | 30 | Number of days of history (1–365) |
[
{ "date": "2025-02-01", "registered_count": 30028 },
{ "date": "2025-02-02", "registered_count": 30105 }
]
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | integer | 1 | Number of days of history: 1 (last 24 hours) or 7 (last 7 days), up to 30 |
[
{ "recorded_at": "2025-02-13 12:00:00", "online_count": 48 },
{ "recorded_at": "2025-02-13 12:05:00", "online_count": 52 }
]
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | integer | 1 | Number of days of history: 1 (last 24 hours) or 7 (last 7 days), up to 30 |
[
{ "recorded_at": "2025-02-13 12:00:00", "lobby_count": 12 },
{ "recorded_at": "2025-02-13 12:05:00", "lobby_count": 14 }
]
Live per-game online counts, historical series, and a compact summary for “all stats” style widgets.
| Parameter | Type | Default | Description |
|---|---|---|---|
| period | string | today | today → last 24h; 7d → last 168h |
{
"period": "today",
"peakOnline": 48,
"peakOnlineAt": "...",
"peakLobbies": 12,
"peakLobbiesAt": "...",
"mostPlayedGame": { "name": "...", "titleId": "...", "peak": 42 },
"gamesWithActivityCount": 15,
"totalSnapshotCount": 288
}
{
"Game Name One": {
"name": "Game Name One",
"online": 42,
"titleId": "4d53006e",
"image": "https://...",
"publisher": "Microsoft Game Studios"
},
"Game Name Two": { ... }
}
| Parameter | Type | Description |
|---|---|---|
| titleId | string | Game title ID (e.g. 4d530064) |
| Parameter | Type | Default | Description |
|---|---|---|---|
| hours | integer | 48 | Hours of history to retrieve |
GET /api/title/4d530064/online-users/history?hours=24
gameName is URL-encoded (e.g. Halo%202).{
"titleId": "4d530064",
"name": "Halo 2",
"title": "Halo 2",
"image": "https://...",
"publisher": "Microsoft Game Studios",
"releaseDate": "2004-11-09"
}
gameName is URL-encoded.{
"titleId": "4d530064",
"gameName": "Halo 2",
"leaderboard_count": 120,
"total_entries": 500000,
"time_entries": 300000,
"score_entries": 200000
}
[
{
"id": 42,
"name": "Leaderboard Name",
"titleId": "4d530064",
"gameName": "Halo 2"
}
]
{
"titleId": "4d530064",
"gameName": "Halo 2",
"leaderboardId": "42",
"name": "Leaderboard Name",
"entries": [
{
"rank": "1",
"name": "PlayerName",
"rating": "1000000",
"timeMs": 120000,
"timeFormatted": "2:00.000",
"isTime": true
}
]
}
Recent leaderboard entry changes (new, updated, or removed).
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Max number of changes to return |
| offset | integer | Offset for pagination |
| game | string | Filter by game name |
["Halo 2", "Project Gotham Racing 2", ...]
days (1–365, default 30).days (default 30), optional limit to cap rows.{
"titleId": "4d53004b",
"gameName": "Project Gotham Racing 2",
"matches": [
{
"hostName": "PlayerName",
"currentPlayers": 8,
"maxPlayers": 8,
"timestamp": "2025-02-13 12:00:00"
}
]
}
/api/title/:titleId/matches). Path uses the same hex title ID as other /api/title/... routes.hours (default 24)./api/title/:titleId/matches or /api/game/:titleId/matches.hours. Prefer /api/title/:titleId/matches/history./api/title/:titleId/matches/stats.Search leaderboard data by player, time, rating, or structured queries.
time (required), tolerance (ms, optional).{
"searchTime": "1:23.456",
"searchTimeMs": 83456,
"tolerance": 0,
"results": [ ... ],
"count": 0
}
names — comma-separated list (max 20).players — array of { playerName, rank }.tolerance (ms), titleId (optional).titleId (optional).Endpoints may return:
{
"error": "Error message description"
}
Common HTTP status codes:
There are no rate limits on the public API. Please use it responsibly.