---
title: "List an organization's matches"
method: POST
path: "/orgs/{identifier}/matches"
tags: ["Match Discovery"]
---

# List an organization's matches

`POST /orgs/{identifier}/matches`

Returns matches across all teams in an organization (resolved by id or slug), newest first, with cursor pagination. The authenticated user must be an active member of the organization. Requires the matches.org_matches:read permission.

## Path parameters

- `identifier` string, required — Organization 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)