---
title: "Get all map scores"
method: GET
path: "/matches/{matchId}/scores"
tags: ["Match Discovery"]
---

# Get all map scores

`GET /matches/{matchId}/scores`

## Request

- Base URL: `https://teambattles.gg/api/v1`
- URL: `https://teambattles.gg/api/v1/matches/{matchId}/scores`
- Auth: HTTP bearer

Retrieve every map score for a match plus a series summary. Returns the full unpaginated list of map scores (no cursor or limit) and a seriesScore counting map wins per side, computed only from CONFIRMED maps and awarding a map to the side with the strictly higher score (equal scores count for neither). Each score's scoreStatus is CONFIRMED or PENDING; submittedBy, confirmedBy, and createdAt may be null. Screenshot URLs are suppressed (empty array) for any score whose API-uploaded image has not passed content moderation. Requires one of matches.user_matches:read, matches.team_matches:read, or matches.org_matches:read. The caller must be an active member of one of the match's two teams; non-participants receive 403, unless they hold a TeamBattles staff role, which can read any match's scores.

## Path parameters

- `matchId` string, required: Match id.

## Response `200`

All map scores for the match with a series summary.

- MapScores: All map scores for a match with a series summary.
  - `scores` MapScoreItem[], required
    - `mapIndex` integer, required
    - `mapId` string, required
    - `creatorTeamScore` integer, required
    - `opponentTeamScore` integer, required
    - `screenshotUrls` string[], required
    - `scoreStatus` string, required: CONFIRMED or PENDING.
    - `submittedBy` ScoreSubmitter, required: Identity of the captain who submitted a score.
      - `userId` string, required
      - `teamId` string, required
      - `name` string, nullable, required
    - `confirmedBy` ScoreConfirmer, required: Identity of the captain who confirmed a score.
      - `userId` string, required
      - `teamId` string, required
      - `confirmedAt` string, nullable, required: Confirmation time (ISO 8601).
    - `createdAt` string, nullable, required: Creation time (ISO 8601).
  - `seriesScore` object, required
    - `creatorMapWins` integer, required
    - `opponentMapWins` integer, required
  - `timestamp` string, required: Response timestamp (ISO 8601).

## Other responses

- `401`: Missing or invalid API key.
- `403`: API key lacks the required permission.
- `404`: Resource not found.

## Changes

- **2026-06-10** `82f2480cdb83`: 2 info
  - api tag `Match Discovery` added
  - api tag `Matches` removed
- **2026-06-04** `f22bd61fd595`: 2 info
  - api tag `Matches` added
  - api tag `Match Discovery` removed

[Operation history](https://skmtc.dev/teambattles/apis/teambattles-api/changes/matches/:matchId/scores/get.md)

---

[API](https://skmtc.dev/teambattles/apis/teambattles-api.md) - [All operations](https://skmtc.dev/teambattles/apis/teambattles-api/llms.txt) - [OpenAPI document](https://skmtc.dev/teambattles/apis/teambattles-api/revisions/75b07daef7dc?raw)