# Get a leaderboard

> The top members for one period, category and metric, best first.

Source: https://docs.stxapp.io/api/rest/leaderboard/get-leaderboard/

The top members for one period, category and metric, best first. `value` is a dollar string for money metrics, an integer for counts and a `0..1` number for ratios. Rows carry a public handle, avatar path and top sport, never an account id. An unknown `category` is not an error; the board is simply empty. A board STX hides is empty with `shown: false`.

```http
GET /api/v1/leaderboard
```

Send it with your own demo key: [Try it](/quick-start/?op=leaderboard_get#try-it).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `period` | `query` | `daily` \| `weekly` \| `monthly` \| `yearly` \| `all` | no | The ranking window, on America/New_York calendar days: `daily` is today, `weekly` from Monday, `monthly` from the 1st, `yearly` from 1 January, `all` lifetime. Default `weekly`. |
| `category` | `query` | string | no | `all` (default) or a sport key, as in a row's `top_sport`, e.g. `basketball`. An unknown key has no rankings: an empty board, or an unranked standing on `/me`. |
| `metric` | `query` | `volume` \| `profit` \| `predictions` \| `markets` \| `win_rate` \| `biggest_win` \| `return` \| `streak` | no | The board: notional traded (`filled × max_price`), net profit, contracts settled, markets settled, win rate, biggest single win, return (profit ÷ volume) or longest winning streak. Default: the board STX opens on. |
| `limit` | `query` | integer | no | Rows to return. Defaults to 100 and is silently clamped to the number of members STX shows per board (at most 100). There is no cursor. |

## Responses

| Status | Description | Schema |
|---|---|---|
| `200` | Success | Leaderboard |
| `400` | A parameter was missing or invalid. | Error |
| `401` | No credential, a bad signature, or a bearer token that is expired, invalid or not a member's. With any signing header present the API-key rules apply and the body is {"error":"Missing or invalid API key credentials"}; otherwise {"error":"Unauthorized"}. | Error |
| `403` | The account behind this key is not active, for example it is pending approval or suspended. Body: {"error":"Your account is suspended. Contact support."}, the message naming the account's status. | Error |
| `404` | The leaderboard is not enabled in this environment. Body: {"error":"Leaderboard is not enabled"} | Error |

## Example

Request:

```bash
curl --request GET \
  --url 'https://demo.stxapp.io/api/v1/leaderboard' \
  --header 'X-STX-ACCESS-KEY: <key-id>' \
  --header 'X-STX-ACCESS-TIMESTAMP: <unix-ms>' \
  --header 'X-STX-ACCESS-SIGNATURE: <base64-ed25519>'
```

Response `200`:

```json
{
  "category": "string",
  "leaderboard": [
    {
      "avatar_url": null,
      "handle": null,
      "rank": null,
      "top_sport": null,
      "top_sport_icon_url": null,
      "value": null
    }
  ],
  "metric": "volume",
  "next_reset_at": null,
  "period": "daily",
  "refreshed_at": null,
  "shown": false
}
```

### Response fields

| Field | Type | Description |
|---|---|---|
| `category` | string | `all` or a sport key. |
| `metric` | string | The metric the rows are ranked on. |
| `next_reset_at` | date-time | When this period's board resets: local midnight in America/New_York on the next boundary, as UTC. `null` for `all`, which never resets, and before the first snapshot. |
| `period` | string | The period the board covers. |
| `refreshed_at` | date-time | When this snapshot was built. `null` before the first snapshot is published. |
| `shown` | boolean | Whether STX shows this board to members. `false` means the board is hidden and `leaderboard` is empty, not that nobody has ranked yet. |
| `avatar_url` | string | Path of the member's avatar, `/avatars/{handle}.svg`, relative to the API host. `null` when `handle` is `null`. |
| `handle` | string | The member's public handle. `null` for a member who has not set one. |
| `rank` | integer | Dense rank, 1-based. Tied values share a rank. |
| `top_sport` | string | The sport the member traded most in the period, as a category key. On a sport board it is that sport. `null` when unknown. |
| `top_sport_icon_url` | string | Path of the sport's icon, the same category icon the apps use, relative to the API host. `null` when `top_sport` is `null`. |
| `value` |  | The ranked value. A dollar string on money boards, an integer on count boards and a number from 0 to 1 on ratio boards. |