---
title: "Player Level and XP Progress"
method: GET
path: "/levels/brand/{brandId}/player/{playerId}"
tags: ["Levels"]
---

# Player Level and XP Progress

`GET /levels/brand/{brandId}/player/{playerId}`

Current level, XP progress, and rewards for reaching the next level. Use this to render the XP progress bar and level badge.

Draw the progress bar as `xpProgressInCurrentLevel / (xpForNextLevel - xpForCurrentLevel)`.

Reward references (`currentLevelRewards[].rewardId`, `nextLevelRewards[].rewardId`) resolve to the rewards catalog (match against `id`).

## Path parameters

- `brandId` string, uuid, required
- `playerId` string, required

## Response `200`

Player level state.

- PlayerLevel
  - `currentLevel` integer — Current level number (1-based).
  - `levelName` string — Display name for the current level (e.g. "Silver", "Gold").
  - `levelIcon` string, nullable — URL to the current level badge icon. `null` if no icon configured.
  - `nextLevelName` string, nullable — Display name for the next level. `null` if at max level.
  - `nextLevelIcon` string, nullable — URL to the next level badge icon. `null` if no icon or at max level.
  - `totalXp` integer — Cumulative XP earned across all levels.
  - `xpForCurrentLevel` integer — Total XP threshold required to reach the current level.
  - `xpForNextLevel` integer, nullable — Total XP threshold required to reach the next level. `null` if at max level.
  - `xpProgressInCurrentLevel` integer — XP earned since entering the current level. Use this to draw the progress bar: `progress / (xpForNextLevel - xpForCurrentLevel)`.
  - `maxLevel` integer — Highest level in the program.
  - `isMaxLevel` boolean — `true` when the player has reached the top level. Hide "next level" UI when this is `true`.
  - `currentLevelRewards` LevelReward[] — Rewards the player received for reaching the current level.
    - `id` string, uuid
    - `levelId` string, uuid
    - `rewardId` string, uuid — Look up in the rewards catalog by matching against `id`.
    - `amount` integer
    - `createdAt` string, date-time
  - `nextLevelRewards` LevelReward[] — Rewards the player will receive upon reaching the next level. Show as incentive.
    - `id` string, uuid
    - `levelId` string, uuid
    - `rewardId` string, uuid — Look up in the rewards catalog by matching against `id`.
    - `amount` integer
    - `createdAt` string, date-time
  - `claimableLevels` ClaimableLevel[] — Levels the player has reached but not yet claimed that carry rewards. Empty or omitted when nothing is claimable. Each entry drives a per-level "Claim" button. Call the claim-level-reward endpoint with the entry's `levelNumber` (and the active `levelConfigId` from the per-config endpoint) to grant the reward and remove the entry from this array.
    - `levelNumber` integer — The level number being claimed. Pass as `levelNumber` to the claim-level-reward endpoint.
    - `name` string — Display name of the level (e.g. "Bronze").
    - `levelIcon` string, nullable — URL to the level badge icon. `null` if no icon configured.
    - `rewards` LevelReward[] — Rewards attached to this level. `rewards[].rewardId` resolves to the rewards catalog `id`.
      - `id` string, uuid
      - `levelId` string, uuid
      - `rewardId` string, uuid — Look up in the rewards catalog by matching against `id`.
      - `amount` integer
      - `createdAt` string, date-time

## Other responses

- `404` — Resource not found (brand, player, mission, leaderboard, etc.).

---

[API](https://skmtc.net/optimove/apis/optimove-api.md) · [All operations](https://skmtc.net/optimove/apis/optimove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/optimove/optimove-api/revisions/fc55c5b1bec5/schema)