---
title: "Get Leaderboard Placement"
method: GET
path: "/api/v1/user/leaderboard/placement"
tags: ["Leaderboard"]
---

# Get Leaderboard Placement

`GET /api/v1/user/leaderboard/placement`

Placement(s) for the authenticated user. When sub_account is omitted, returns one entry per user trading subaccount; otherwise exactly one entry. When the user has no trading subaccounts, data is an empty array. If the account is not ranked, ranked is false and place is "0".

## Query parameters

- `sub_account` string, nullable
- `timeframe` 'today' | '7d' | '30d' | 'all', required — Leaderboard ranking window: today, last 7 days, last 30 days, or all time.

## Response `200`

Placements (ranked false when not on board)

- LeaderboardPlacementResponse — Response for the current user's placement(s) on the leaderboard.
  - `data` LeaderboardData[], required — One row per subaccount (or single row when sub_account query is set).
    - `account_value` string, required — Equity in quote units (e.g. USDC).
    - `place` string, required — Rank position (1-based), or "0" when not ranked.
    - `pnl` string, required — Unrealised PnL in quote units.
    - `ranked` boolean, required — Whether this entry is on the board (false when not ranked).
    - `referral_xp` integer, required — XP earned from referral bonuses.
    - `roi` string, required — Return on investment as a decimal string (e.g. "0.05" for 5%).
    - `sub_account_address` string, required — Subaccount address.
    - `total_xp` integer, required — Total XP balance.
    - `trading_xp` integer, required — XP earned from trading activity.
    - `volume` string, required — Cumulative volume in quote units.

## Other responses

- `400` — Bad Request (invalid sub_account or address)
- `401` — Unauthorized

---

[API](https://skmtc.net/ekidenfi/apis/ekiden-gateway.md) · [All operations](https://skmtc.net/ekidenfi/apis/ekiden-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ekidenfi/ekiden-gateway/revisions/75ffe546b73a/schema)