Querying Results

This guide explains how to retrieve user achievements, progress, and achievement history through the Query Gateway.

Overview

The Query API provides endpoints for:

Getting a user's achievements
Getting achievement progress
Viewing achievement history
Getting specific achievement details

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

Get User Achievements

Get all achievements for a user, including locked, in-progress, and unlocked achievements.

Endpoint:

GET /v1/achievements/user/{user_id}

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `locked`, `in_progress`, `unlocked` (optional)
`limit`	integer	Page size (default: 50)
`offset`	integer	Page offset

Example Request:

GET /v1/achievements/user/user_123?status=unlocked

Response:

{
  "achievements": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "First Victory",
      "description": "Win your first match",
      "badge_url": "https://example.com/badges/first-victory.png",
      "status": "unlocked",
      "progress": {
        "current": 1,
        "threshold": 1,
        "percentage": 100.0
      },
      "unlocked_at": "2026-01-20T10:30:00Z",
      "rewards_granted": true
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Century Club",
      "description": "Win 100 matches",
      "badge_url": "https://example.com/badges/century-club.png",
      "status": "in_progress",
      "progress": {
        "current": 75,
        "threshold": 100,
        "percentage": 75.0
      },
      "unlocked_at": null,
      "rewards_granted": false
    }
  ],
  "total": 25,
  "unlocked_count": 12,
  "in_progress_count": 8,
  "locked_count": 5
}

Get Achievement Progress

Get detailed progress for a specific achievement.

Endpoint:

GET /v1/achievements/user/{user_id}/{achievement_id}

Example Request:

GET /v1/achievements/user/user_123/660e8400-e29b-41d4-a716-446655440001

Response:

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Century Club",
  "description": "Win 100 matches",
  "badge_url": "https://example.com/badges/century-club.png",
  "status": "in_progress",
  "progress": {
    "current": 75,
    "threshold": 100,
    "percentage": 75.0,
    "remaining": 25
  },
  "criteria": {
    "type": "event_count",
    "event_type": "match.completed",
    "threshold": 100
  },
  "unlocked_at": null,
  "rewards_granted": false
}

Get Achievement History

Get a user's achievement unlock history.

Endpoint:

GET /v1/achievements/user/{user_id}/history

Query Parameters:

Parameter	Type	Description
`limit`	integer	Page size (default: 20)
`offset`	integer	Page offset

Example Request:

GET /v1/achievements/user/user_123/history?limit=10

Response:

{
  "history": [
    {
      "achievement_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "First Victory",
      "badge_url": "https://example.com/badges/first-victory.png",
      "unlocked_at": "2026-01-28T10:30:00Z",
      "rewards": [
        {
          "item_id": "victory-badge",
          "name": "Victory Badge",
          "reward_type": "badge"
        }
      ]
    },
    {
      "achievement_id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "XP Master",
      "badge_url": "https://example.com/badges/xp-master.png",
      "unlocked_at": "2026-01-27T15:45:00Z",
      "rewards": [
        {
          "item_id": "xp-master-badge",
          "name": "XP Master Badge",
          "reward_type": "badge"
        },
        {
          "item_id": "gold-5000",
          "name": "5000 Gold Coins",
          "reward_type": "currency"
        }
      ]
    }
  ],
  "total": 12
}

Get All Available Achievements

Get all achievements available in the system (for displaying to users).

Endpoint:

GET /v1/achievements

Query Parameters:

Parameter	Type	Description
`active`	boolean	Filter by active status (default: true)
`limit`	integer	Page size (default: 50)
`offset`	integer	Page offset

Example Request:

GET /v1/achievements/?active=true

Response:

{
  "achievements": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "First Victory",
      "description": "Win your first match",
      "badge_url": "https://example.com/badges/first-victory.png",
      "criteria": {
        "type": "event_count",
        "event_type": "match.completed",
        "threshold": 1
      },
      "active": true
    }
  ],
  "total": 25
}

JavaScript Example

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

  async getUserAchievements( userId, options = {}) {
    const params = new URLSearchParams(options);
    
    const response = await fetch(
      `${this.apiUrl}/v1/achievements/user/${userId}?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwt}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.json();
  }

  async getAchievementProgress(userId, achievementId) {
    const response = await fetch(
      `${this.apiUrl}/v1/achievements/user/${userId}/${achievementId}`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwt}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.json();
  }

  async getAchievementHistory(userId, options = {}) {
    const params = new URLSearchParams(options);
    
    const response = await fetch(
      `${this.apiUrl}/v1/achievements/user/${userId}/history?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwt}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.json();
  }
}

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

// Get user's achievements
const { achievements: userAchievements, unlocked_count } = await achievements.getUserAchievements(
  'user_123',
  { status: 'unlocked' }
);
console.log(`Unlocked ${unlocked_count} achievements`);

// Get progress for specific achievement
const progress = await achievements.getAchievementProgress(
  'user_123',
  '660e8400-e29b-41d4-a716-446655440001'
);
console.log(`${progress.progress.current}/${progress.progress.threshold} (${progress.progress.percentage}%)`);

// Get achievement history
const { history } = await achievements.getAchievementHistory('user_123');
history.forEach(entry => {
  console.log(`Unlocked: ${entry.name} on ${entry.unlocked_at}`);
});

Best Practices

Show Progress: Display progress bars for in-progress achievements
Celebrate Unlocks: Notify users when achievements are unlocked
Achievement Gallery: Show all available achievements to encourage engagement
Recent Unlocks: Display recently unlocked achievements prominently
Progress Tracking: Update progress in real-time after relevant events
Badge Display: Show achievement badges in user profiles and leaderboards

Next Steps

Creating Achievements - Learn how to create achievement systems
Achievements Overview - Understand the achievements system

Querying Results

On this page