Querying Results

This guide explains how to retrieve user level information, XP data, and level progression through the Query Gateway.

Overview

The Query API provides endpoints for:

Getting a user's current level and XP
Getting level progression details
Viewing level history
Getting XP transaction history

All endpoints require authentication. See Getting Started for authentication setup.

Get User Level

Get a user's current level, total XP, and progress to the next level.

Endpoint:

GET /v1/levels/user/{user_id}?tenant_id=${tenant_id}

Example Request:

GET /v1/levels/user/user_123?tenant_id=${tenant_id}

Response:

{
  "tenant_id": "your_tenant",
  "user_id": "user_123",
  "level_system_id": "main-progression",
  "current_level": 5,
  "level_name": "Expert",
  "total_xp": 1250,
  "xp_for_current_level": 1000,
  "xp_for_next_level": 1500,
  "xp_to_next_level": 250,
  "progress_percentage": 50.0
}

Get Level Details

Get detailed information about a specific level.

Endpoint:

GET /v1/levels/level/{level_number}?tenant_id=${tenant_id}

Example Request:

GET /v1/levels/level/5?tenant_id=${tenant_id}

Response:

{
  "level": 5,
  "name": "Expert",
  "xp_required": 1000,
  "description": "Expert level player",
  "rewards": [
    {
      "item_id": "expert-badge",
      "name": "Expert Badge",
      "reward_type": "badge"
    }
  ]
}

Get XP Transaction History

Get a user's XP earning history.

Endpoint:

GET /v1/wallet/transactions?user_id={user_id}&currency_id=xp?tenant_id=${tenant_id}

Query Parameters:

Parameter	Type	Description
`user_id`	string	Required. User ID
`currency_id`	string	Filter by currency (use "xp")
`limit`	integer	Page size (default: 50, max: 100)
`offset`	integer	Page offset (default: 0)

Example Request:

GET /v1/wallet/transactions?tenant_id=${tenant_id}&user_id=user_123&currency_id=xp&limit=20

Response:

{
  "transactions": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "currency_id": "xp",
      "amount": 50,
      "balance_after": 1250,
      "source_type": "earning_rule",
      "source_ref": "match_completion_xp",
      "description": "Match completion XP",
      "created_at": "2026-01-28T10:30:00Z"
    },
    {
      "id": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
      "currency_id": "xp",
      "amount": 100,
      "balance_after": 1200,
      "source_type": "earning_rule",
      "source_ref": "victory_bonus_xp",
      "description": "Victory bonus XP",
      "created_at": "2026-01-28T09:15:00Z"
    }
  ],
  "total": 45
}

Get Level Progression

Get detailed progression information including all levels and user's position.

Endpoint:

GET /v1/levels/progression?tenant_id=${tenant_id}&user_id={user_id}

Example Request:

GET /v1/levels/progression?user_id=user_123&tenant_id=${tenant_id}

Response:

{
  "user_id": "user_123",
  "current_level": 5,
  "total_xp": 1250,
  "levels": [
    {
      "level": 1,
      "name": "Beginner",
      "xp_required": 0,
      "achieved": true,
      "achieved_at": "2026-01-15T08:00:00Z"
    },
    {
      "level": 2,
      "name": "Novice",
      "xp_required": 100,
      "achieved": true,
      "achieved_at": "2026-01-16T10:30:00Z"
    },
    {
      "level": 3,
      "name": "Apprentice",
      "xp_required": 300,
      "achieved": true,
      "achieved_at": "2026-01-20T14:20:00Z"
    },
    {
      "level": 4,
      "name": "Veteran",
      "xp_required": 600,
      "achieved": true,
      "achieved_at": "2026-01-25T16:45:00Z"
    },
    {
      "level": 5,
      "name": "Expert",
      "xp_required": 1000,
      "achieved": true,
      "achieved_at": "2026-01-27T11:00:00Z"
    },
    {
      "level": 6,
      "name": "Master",
      "xp_required": 1500,
      "achieved": false,
      "xp_progress": 250,
      "progress_percentage": 50.0
    }
  ]
}

JavaScript Example

class LevelsClient {
  constructor(apiUrl, jwt) {
    this.apiUrl = apiUrl;
    this.jwt = jwt;
  }

  async getUserLevel(tenantId, userId) {
    const response = await fetch(
      `${this.apiUrl}/v1/levels/user/${userId}&tenant_id=${tenant_id}`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwt}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error('Failed to fetch user level');
    }
    
    return response.json();
  }

  async getXPTransactions(tenantId, userId, options = {}) {
    const params = new URLSearchParams({
      user_id: userId,
      currency_id: 'xp',
      ...options
    });
    
    const response = await fetch(
      `${this.apiUrl}/v1/wallet/transactions?${params}&tenant_id=${tenant_id}`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwt}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.json();
  }

  async getProgression(tenantId, userId) {
    const response = await fetch(
      `${this.apiUrl}/v1/levels/progression?user_id=${userId}&tenant_id=${tenant_id}`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwt}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.json();
  }
}

// Example usage
const levels = new LevelsClient('https://query.phoenix.example.com', userJwt);

// Get user's current level
const levelInfo = await levels.getUserLevel('user_123');
console.log(`Level ${levelInfo.current_level} (${levelInfo.level_name})`);
console.log(`${levelInfo.xp_to_next_level} XP to next level`);

// Get XP history
const { transactions } = await levels.getXPTransactions('user_123', {
  limit: 10
});
transactions.forEach(t => {
  console.log(`+${t.amount} XP: ${t.description}`);
});

// Get full progression
const progression = await levels.getProgression('user_123');
console.log(`Current level: ${progression.current_level}`);
console.log(`Total XP: ${progression.total_xp}`);

Best Practices

Cache Level Data: Cache level information to reduce API calls
Show Progress: Display XP progress bars and next level requirements
Celebrate Milestones: Notify users when they level up
XP History: Show recent XP earnings to encourage engagement
Level Comparison: Allow users to see their progress compared to others
Real-time Updates: Poll level data after XP-earning events

Next Steps

Creating Levels - Learn how to configure level systems
Levels Overview - Understand the levels system

Querying Results

On this page