Querying Results

1. Authentication

Query endpoints accept the same mechanisms as the Admin Gateway:

• X-API-Key: <ADMIN_API_KEY> or Authorization: Bearer <ADMIN_API_KEY> for full-control server integrations.
• Tenant HMAC headers (X-Tenant-Id, X-Timestamp, X-Signature) if you expose the API directly to trusted partners.

Most customers use API keys for backend-to-backend calls and relay simplified data to clients over their own APIs.

2. Endpoint Overview

All timestamps for snapshots use RFC3339 (ISO 8601) strings, e.g., 2025-11-18T12:00:00Z.

3. Live Leaderboard Pages

GET /v1/leaderboards/{tenant_id}/{leaderboard_id}?limit=50&offset=0

Parameters:

• limit – number of entries to return (default 100, max tuned by Phoenix).
• offset – zero-based offset for pagination.
• window_key – optional. Use "current" or a specific window identifier (e.g., 2025-11-18T12). If omitted, Phoenix chooses the active window and falls back to the most recent completed window when live data is empty.

Sample response (abbreviated):

{
  "leaderboard_id": "xp-weekly-global",
  "tenant_id": "tenant-prod-001",
  "window_key": "2025-W47",
  "entries": [
    { "user_id": "user-123", "score": 12850, "rank": 1 },
    { "user_id": "user-456", "score": 12510, "rank": 2 }
  ],
  "total_entries": 75432,
  "limit": 50,
  "offset": 0,
  "reward_config": {
    "reward_config_id": "weekly-top100",
    "tiers": [
      {
        "rank_start": 1,
        "rank_end": 1,
        "items": [{ "type": "coins", "amount": 10000 }]
      }
    ]
  }
}

reward_config is present when the window is complete and a reward definition exists.

4. Around a Specific User

GET /v1/leaderboards/{tenant_id}/{leaderboard_id}/user/{user_id}?limit=25

Returns a page centered around the requested user (helpful for “You and rivals” widgets). The response structure matches the standard page, ensuring your UI can reuse the same rendering logic.

If the user has no score in the requested window, Phoenix returns entries representing the top of the leaderboard plus reward_config (if applicable); total_entries still reflects all participants.

5. Quick Rank & Score Lookups

Use these lightweight endpoints for profile screens or matchmaking overlays:

• Rank: GET /v1/leaderboards/{tenant_id}/{leaderboard_id}/rank/{user_id}
• Score: GET /v1/leaderboards/{tenant_id}/{leaderboard_id}/score/{user_id}

Responses include found: true/false. When found is false, rank and score default to 0. Rankings are 1-indexed.

Tip: Cache these results briefly (15–30 seconds). They’re sourced from the same live data as the page endpoints but skip pagination overhead.

6. Window Selection Rules

• If window_key is omitted, Phoenix decides automatically:
  • Active window with live data takes priority.
  • If the live window is empty (e.g., just reset), Phoenix falls back to the latest completed snapshot.
• To pin a specific window:
  • For live/hourly/daily windows, pass the exact window_key you received earlier.
  • For snapshots, use the window_key from /v1/snapshots responses.
• Special case: window_key=current forces the current window even if no entries exist yet.

When a requested window doesn’t exist, the API returns 404 with a descriptive message.

7. Error Reference

Phoenix always responds with the standard error envelope described earlier in this guide.

8. Integration Tips

• Cache frequently accessed pages to reduce latency (e.g., top 100 refreshed every few seconds).
• Use the WebSocket stream for push updates, but fall back to REST pages when reconnecting.
• Always display the window_key somewhere in your UI so players know which time period they’re viewing.
• Validate limit/offset inputs server-side before proxying requests from clients.
• Combine /user/{user_id} pages with WebSocket watchlists for personalized companion apps.

With querying in place, your integration now covers ingestion, administration, real-time streams, and REST retrieval. You’re ready to QA the full leaderboard experience end-to-end.