# Get competition leaderboard

```http
GET /api/public/v1/competitions/{competitionId}/leaderboard
```

**Scope**: `competition.read`.

Returns a cursor-paginated public leaderboard. Before publication, every competition returns an empty page with `meta.published: false`.

## Parameters

| Parameter | Location | Type | Required | Default | Description |
| :--- | :--- | :--- | :---: | :--- | :--- |
| `competitionId` | path | string | Yes | — | Competition ID. |
| `cursor` | query | string | No | — | Opaque cursor from the previous page. |
| `limit` | query | integer | No | `25` | Page size from `1` through `100`. |

## Response DTO

```ts
type GetCompetitionLeaderboardResponse = {
  ok: true;
  data: {
    items: LeaderboardEntry[];
    nextCursor: string | null;
    meta: {
      published: boolean;
      publishedAt: string | null;
    };
  };
};

type LeaderboardEntry = {
  rank: number;
  teamId?: string;
  teamNumber: string | null;
  teamName: string;
  score: number;
  scoreablePairs?: number;
};
```

Stage 1 entries do not expose `teamId`. IGP24 entries additionally include `scoreablePairs`.

## Modular Arithmetic Challenge example

```bash
curl "https://api.sair.foundation/api/public/v1/competitions/modular-arithmetic-challenge/leaderboard?limit=25" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

```json
{
  "ok": true,
  "data": {
    "items": [
      {
        "rank": 1,
        "teamId": "teamv2_0e52064c5e864ffd9f4e7532f4de63d0",
        "teamNumber": "MAC-T00001",
        "teamName": "Example Team",
        "score": 0.987
      }
    ],
    "nextCursor": null,
    "meta": {
      "published": true,
      "publishedAt": "2026-10-01T00:00:00Z"
    }
  }
}
```

## Mathematics Distillation Stage 1 example

```bash
curl "https://api.sair.foundation/api/public/v1/competitions/mathematics-distillation-challenge-equational-theories-stage1/leaderboard?limit=25" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

```json
{
  "ok": true,
  "data": {
    "items": [
      {
        "rank": 1,
        "teamNumber": "MDC1-T00001",
        "teamName": "MDC1-T00001",
        "score": 0.941
      }
    ],
    "nextCursor": null,
    "meta": {
      "published": true,
      "publishedAt": "2026-10-01T00:00:00Z"
    }
  }
}
```

## Mathematics Distillation Stage 2 example

```bash
curl "https://api.sair.foundation/api/public/v1/competitions/mathematics-distillation-challenge-equational-theories-stage2/leaderboard?limit=25" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

```json
{
  "ok": true,
  "data": {
    "items": [
      {
        "rank": 1,
        "teamId": "teamv2_19ac4fb862d64502ae7837852e18fb4a",
        "teamNumber": "MDC2-T00003",
        "teamName": "Lean Explorers",
        "score": 0.963
      }
    ],
    "nextCursor": null,
    "meta": {
      "published": true,
      "publishedAt": "2026-10-01T00:00:00Z"
    }
  }
}
```

## IGP24 example

```bash
curl "https://api.sair.foundation/api/public/v1/competitions/igp24/leaderboard?limit=25" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

```json
{
  "ok": true,
  "data": {
    "items": [
      {
        "rank": 1,
        "teamId": "teamv2_a7a863ce80e6447881ad068bab82498e",
        "teamNumber": "IGP24-T00007",
        "teamName": "Galois Wranglers",
        "score": 42.75,
        "scoreablePairs": 57
      }
    ],
    "nextCursor": "eyJhZnRlciI6WzQyLjc1LCJ0ZWFtdjJfYTdhODYzY2U4MGU2NDQ3ODgxYWQwNjhiYWI4MjQ5OGUiXX0",
    "meta": {
      "published": true,
      "publishedAt": "2026-08-01T00:00:00Z"
    }
  }
}
```

## Before publication

```json
{
  "ok": true,
  "data": {
    "items": [],
    "nextCursor": null,
    "meta": {
      "published": false,
      "publishedAt": null
    }
  }
}
```

## Errors

| HTTP | Code | When |
| :---: | :--- | :--- |
| `400` | `MALFORMED_BODY` | The cursor is invalid. |

See [Errors](../../../errors.md) for common errors.