# Get leaderboard

```http
GET /api/public/v1/competitions/modular-arithmetic-challenge/leaderboard
```

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

Returns one ranked row per team from the latest published Modular Arithmetic official evaluation batch. Only completed, ranking-eligible entries participate.

A request without `cursor` selects the latest published batch. A continuation request stays on the batch identified by its cursor, even if a newer batch becomes current.

## Query parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `cursor` | string | No | — | Opaque, batch-bound cursor returned by the previous page. |
| `limit` | integer | No | `25` | Page size from `1` through `100`. |

Do not decode, modify, or construct cursors. Pass `nextCursor` unchanged to this endpoint; start a fresh traversal by omitting `cursor`.

## Publication and snapshot behavior

The response has two publication states:

- When `meta.published` is `false`, `items` is empty, `nextCursor` is `null`, and both `meta.publishedAt` and `meta.batch` are `null`.
- When `meta.published` is `true`, `meta.publishedAt` is an ISO 8601 timestamp and `meta.batch` identifies the immutable official batch used for the page.

Publication is an information boundary. The unpublished response exposes no batch, result, team, model-reference, or member data. A published response includes only completed entries that organizers marked ranking-eligible.

Ranks, metrics, and `bestEntries` come from the cursor-bound official batch and do not change during that traversal. `teamName`, `teamNumber`, and `teamDetails` are current public display projections; they may change independently of the frozen evaluation results. Use `teamId` as the team identity.

Every `entryId` returned from a published batch identifies that immutable official result and remains usable with [Get a leaderboard entry](./get-leaderboard-entry.md), including when a newer batch is later published.

## Ranking rules

Each team appears at most once. The server selects the team's best completed, eligible entry by comparing these metrics in order:

1. Higher `highestTierAbove90` wins. The value is the highest tier from T1 through T10 completed with at least 90% accuracy; `-1` means no scored tier reached that threshold.
2. If the tier is equal, higher `overallAccuracy` wins. This is the mean accuracy across T1 through T10.

If multiple entries from the same team share its best metric pair, all of them appear in `bestEntries`. Teams with equal metric pairs share the same competition rank, using competition ranking such as `1, 1, 3`. The server applies a deterministic display order within a tie; clients must preserve the returned item order.

## Response fields

### Data

| Field | Type | Always present | Description |
| :--- | :--- | :---: | :--- |
| `items` | [`ModularArithmeticLeaderboardEntry[]`](#modulararithmeticleaderboardentry) | Yes | Current page in server-provided official rank order. Empty when `meta.published` is `false`. |
| `nextCursor` | string \| null | Yes | Cursor for the next page, or `null` when the traversal is complete. |
| `meta` | [`ModularArithmeticLeaderboardMeta`](#modulararithmeticleaderboardmeta) | Yes | Publication state and official batch metadata. |

### `ModularArithmeticLeaderboardEntry`

| Field | Type | Always present | Description |
| :--- | :--- | :---: | :--- |
| `rank` | integer | Yes | One-based competition rank from the batch. Equal metric pairs share a rank. |
| `teamId` | string | Yes | Opaque Competition Team ID and stable identity for the row. |
| `teamNumber` | string \| null | Yes | Current public competition team number, or `null` when none is assigned. |
| `teamName` | string | Yes | Current public team display name, falling back to the team number or ID when no name is available. |
| `score` | number | Yes | Compatibility alias equal to `overallAccuracy`. Do not use this field alone to re-rank the response. |
| `highestTierAbove90` | integer | Yes | Primary metric: `-1`, or the highest T1–T10 tier completed with at least 90% accuracy. |
| `overallAccuracy` | number | Yes | Secondary metric from `0` through `1`: mean accuracy across T1–T10. |
| `bestEntries` | [`ModularArithmeticBestEntry[]`](#modulararithmeticbestentry) | Yes | Every official entry tied at the team's best `(highestTierAbove90, overallAccuracy)` pair. Contains at least one entry. |
| `teamDetails` | [`TeamMemberDetails`](../../competitions.md#leaderboard-team-details-and-privacy) \| null | Yes | Current consent-gated, server-redacted member projection. `null` means the projection is unavailable. |

### `ModularArithmeticBestEntry`

| Field | Type | Always present | Description |
| :--- | :--- | :---: | :--- |
| `entryId` | string | Yes | Opaque, immutable official-result entry ID. Pass it as `{entryId}` to [Get a leaderboard entry](./get-leaderboard-entry.md). |
| `formalSubmissionId` | string | Yes | Opaque formal submission ID associated with the evaluated entry. |
| `slot` | integer | Yes | One-based formal submission slot. |
| `repository` | string | Yes | Evaluated Hugging Face repository in `owner/name` form. |
| `commitSha` | string | Yes | Immutable evaluated repository commit. |
| `timedOut` | boolean | Yes | Whether the official evaluation timed out. |

The leaderboard returns entry summaries; per-tier evaluation details are available from [Get a leaderboard entry](./get-leaderboard-entry.md).

### `ModularArithmeticLeaderboardMeta`

| Field | Type | Always present | Description |
| :--- | :--- | :---: | :--- |
| `published` | boolean | Yes | Whether an official leaderboard batch is publicly available in this response. |
| `publishedAt` | string \| null | Yes | ISO 8601 time at which the Competition leaderboard was made public; non-null exactly when `published` is `true`. |
| `batch` | [`ModularArithmeticOfficialBatch`](#modulararithmeticofficialbatch) \| null | Yes | Immutable official evaluation batch used for `items`; non-null exactly when `published` is `true`. |

### `ModularArithmeticOfficialBatch`

| Field | Type | Always present | Description |
| :--- | :--- | :---: | :--- |
| `id` | string | Yes | Opaque official evaluation batch ID. |
| `problemSetId` | string | Yes | Stable problem-set identifier. |
| `problemSetLabel` | string | Yes | Human-readable problem-set label. |
| `problemSetSha256` | string | Yes | SHA-256 digest of the canonical official problem set. |
| `caseCount` | integer | Yes | Total number of official evaluation cases in the batch, including the diagnostic T0 cases. |
| `specCommit` | string | Yes | Evaluation specification commit used by the batch. |
| `scoringVersion` | string | Yes | Scoring contract version used by the batch. |

## Example request

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

## Example response

```json
{
  "ok": true,
  "data": {
    "items": [
      {
        "rank": 1,
        "teamId": "teamv2_0e52064c5e864ffd9f4e7532f4de63d0",
        "teamNumber": "MAC-T00001",
        "teamName": "Example Team",
        "score": 0.93,
        "highestTierAbove90": 8,
        "overallAccuracy": 0.93,
        "bestEntries": [
          {
            "entryId": "mce_3f7a52b902c54f0d9eb416a99d0992ce",
            "formalSubmissionId": "sub_7b91f430fe2e48b9bb2b6dfc65bce386",
            "slot": 1,
            "repository": "example-team/modular-model",
            "commitSha": "abcdef0123456789abcdef0123456789abcdef01",
            "timedOut": false
          }
        ],
        "teamDetails": {
          "members": [
            {
              "name": "Alice Example"
            }
          ]
        }
      }
    ],
    "nextCursor": null,
    "meta": {
      "published": true,
      "publishedAt": "2026-08-14T03:00:00Z",
      "batch": {
        "id": "mcb_3c0a9d2f1e8b4a6f9d7c2b5e8a1d4f6c",
        "problemSetId": "candidate-a-review",
        "problemSetLabel": "A",
        "problemSetSha256": "762a9ee2fb0f40ff205ebcca02526751d7cfcd9df856d1dae74add1768d75334",
        "caseCount": 1100,
        "specCommit": "99cac6ef5c2f82e53105ec0ddcbb9b8d37bf6fca",
        "scoringVersion": "mac-score-v1"
      }
    }
  }
}
```

## Unpublished response

While the Competition leaderboard is unpublished, the endpoint returns:

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

No official batch, result, team, model-reference, or member information is exposed by this response. When published, `teamDetails` is still `null` unless a current public team projection is available; see the shared [team-details privacy rules](../../competitions.md#leaderboard-team-details-and-privacy). Do not infer whether the team declined, the competition disabled details, or no display fields were available.

## Errors

| Status | Code | When |
| :---: | :--- | :--- |
| `400` | `MALFORMED_BODY` | `cursor` is malformed or `limit` is outside `1` through `100`. |
| `404` | `NOT_FOUND` | The competition does not exist or is not publicly visible. |

See [Errors](../../../errors.md) for authentication, scope, rate-limit, and standard error-envelope behavior.