---
title: "List a team's matches"
method: POST
path: "/teams/{identifier}/matches"
tags: ["Match Discovery"]
---

# List a team's matches

`POST /teams/{identifier}/matches`

Returns matches for a specific team (resolved by id or slug), newest first, with cursor pagination. The authenticated user must be an active member of the team. Requires the matches.team_matches:read permission.

## Path parameters

- `identifier` string, required — Team id or slug.

## Request body

- MatchesRequestBody — Filters and cursor pagination for listing matches.
  - `numItems` integer — Page size (1-100). Defaults to 25.
  - `cursor` string, nullable — Opaque continuation cursor from a prior page's continueCursor.
  - `includeStatuses` string[] — Only include matches with these MatchStatus codes; unknown values are ignored.
  - `excludeStatuses` string[] — Exclude matches with these MatchStatus codes; unknown values are ignored.
  - `gameId` string — Filter to a single game by id.
  - `scheduledAfter` string — ISO 8601; only matches scheduled at or after this time.
  - `scheduledBefore` string — ISO 8601; only matches scheduled at or before this time.
  - `createdAfter` string — ISO 8601; only matches created at or after this time.
  - `createdBefore` string — ISO 8601; only matches created at or before this time.
  - `opponentId` string — Filter to matches against this opponent team (team id or slug).

## Response `200`

Cursor-paginated result. continueCursor is non-null even when isDone is true.

- object
  - `page` UserMatch[], required
    - `id` string, required
    - `status` 'PENDING' | 'ACCEPTED' | 'READY' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED' | 'DISPUTED' | 'FORFEITED', required — Lifecycle status of a match.
    - `game` Game, required — Game definition.
      - `id` string, required — Game ID.
      - `nameKey` string, required — Game name key for i18n lookup.
    - `gameMode` string, required — Game mode (e.g. HARDPOINT, SEARCH_AND_DESTROY).
    - `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.
    - `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).
    - `bestOf` integer, required — Number of maps in the series (1, 3, 5, or 7).
  - `isDone` boolean, required
  - `continueCursor` 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.
- `404` — Resource not found.

---

[API](https://skmtc.net/teambattles/apis/teambattles-api.md) · [All operations](https://skmtc.net/teambattles/apis/teambattles-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/teambattles/teambattles-api/revisions/2ffe8fb53b7d/schema)