---
title: "List matches for the developer's approved game"
method: POST
path: "/game/matches"
tags: ["Game: Matches"]
---

# List matches for the developer's approved game

`POST /game/matches`

Returns matches for the API key owner's approved (bound) game, with legacy cursor pagination. Requires the game.lifecycle:read permission.

## Request body

- ListGameMatchesBody — Status filter and cursor pagination for listing the bound key's game matches. The game is derived from the developer-app key's bound game (not a body field).
  - `status` string — Optional MatchStatus filter (e.g. IN_PROGRESS).
  - `limit` number — Page size (1-100, enforced by the handler). Defaults to the handler's internal default.
  - `cursor` string — Opaque continuation cursor from a prior page's pagination.cursor.

## Response `200`

Legacy cursor-paginated result. pagination.cursor is null when there are no more pages.

- object
  - `matches` GameMatch[], required
    - `id` string, required
    - `status` 'PENDING' | 'ACCEPTED' | 'READY' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED' | 'DISPUTED' | 'FORFEITED', required — Lifecycle status of a match.
    - `gameMode` string, required — Game mode identifier (from the match's gameModeId).
    - `bestOf` integer, required — Number of maps in the series (1, 3, 5, or 7).
    - `creatorTeam` Team, required — A team participating in a match.
      - `id` string, required — Team ID.
      - `name` string, required — Team name.
      - `tag` string, required — Team tag (short identifier).
      - `avatarUrl` string, nullable — Team avatar URL.
    - `acceptedTeam` Team, required — A team participating in a match.
      - `id` string, required — Team ID.
      - `name` string, required — Team name.
      - `tag` string, required — Team tag (short identifier).
      - `avatarUrl` string, nullable — Team avatar URL.
    - `creatorTeamScore` integer, nullable, required
    - `acceptedTeamScore` integer, nullable, required
    - `scheduledAt` string, nullable, required — Scheduled start time (ISO 8601).
    - `startedAt` string, nullable, required — Actual start time (ISO 8601).
    - `completedAt` string, nullable, required — Completion time (ISO 8601).
    - `createdAt` string, nullable, required — Creation time (ISO 8601).
  - `count` integer, required
  - `pagination` object, required
    - `cursor` string, nullable, required
    - `hasMore` boolean, required
  - `timestamp` string, required

## Other responses

- `400` — Bad request (invalid body, cursor, limit, or date).
- `401` — Missing or invalid API key.
- `403` — API key lacks the required permission.

## Changes

- **2026-06-10** `82f2480cdb83` — 2 info
  - api tag `Game: Matches` added
  - api tag `Game` removed
- **2026-06-07** `480c7d480b2e` — 2 info
  - added the optional property `matches/items/acceptedTeam/anyOf[#/components/schemas/Team]/avatarUrl` to the response with the `200` status
  - added the optional property `matches/items/creatorTeam/anyOf[#/components/schemas/Team]/avatarUrl` to the response with the `200` status
- **2026-06-05** `0732b7254e17` — 1 warning
  - removed the request property `gameId`
- **2026-06-04** `f22bd61fd595` — 1 breaking, 2 warning, 2 info
  - added the new required request property `gameId`
  - removed the optional property `matches/items/acceptedTeam/anyOf[#/components/schemas/Team]/avatarUrl` from the response with the `200` status
  - removed the optional property `matches/items/creatorTeam/anyOf[#/components/schemas/Team]/avatarUrl` from the response with the `200` status
  - api tag `Game` added
  - …1 more

[Change history](https://skmtc.dev/teambattles/apis/teambattles-api/changes/game/matches/post.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-service-production.skmtc.workers.dev/v1/apis/teambattles/teambattles-api/revisions/2ffe8fb53b7d/schema)