---
title: "List every match of a tournament for content operations"
method: GET
path: "/v1/admin/tournaments/{tournament_id}/matches"
tags: ["Admin Tournament Matches"]
---

# List every match of a tournament for content operations

`GET /v1/admin/tournaments/{tournament_id}/matches`

## Request

- Base URL: `https://api.hify.club`
- URL: `https://api.hify.club/v1/admin/tournaments/{tournament_id}/matches`
- Auth: API key in header `X-User-Token`

Admin only. Returns all of the tournament's matches, completed included, ordered by game start time, court and sequence number, and paged on every request (X-Total-Count / X-Total-Pages). The scorer app's list at /v1/tournaments/{id}/matches is a different view: it hides completed matches and scopes claims to the caller.

## Query parameters

- `date` string, date
- `arena_id` integer
- `status` 'pending' | 'in_progress' | 'completed'
- `search` string
- `page` integer
- `per_page` integer

## Response `200`

Matches

- AdminTournamentMatch[]
  - `id` integer
  - `external_id` string, nullable: The partner's match id when the match came from a feed.
  - `game_id` integer
  - `sequence_number` integer, nullable
  - `round_number` integer, nullable
  - `stage` 'league' | 'quarterfinal' | 'semifinal' | 'knockout' | 'final' | 'third_place'
  - `category` string, nullable: Display label, e.g. "Open Mixed Doubles".
  - `status` 'pending' | 'in_progress' | 'completed'
  - `winner_side` 'side_a' | 'side_b' | 'draw', nullable
  - `completion_reason` string, nullable
  - `scoring_format_id` integer, nullable
  - `court_number` integer, nullable: The arena's in_facility_id.
  - `started_at` string, date-time, nullable: scored_at of the match's first non-voided score entry, the same value the scorer app's Match.started_at carries. Null until the match has been scored. The game's start_time is the slot; this is the match.
  - `ended_at` string, date-time, nullable: scored_at of the match's last non-voided score entry. Null until the match has been scored.
  - `sides` object: Both keys are always present.
    - `side_a` AdminMatchParticipant[]
      - `id` integer
      - `participant_type` 'User' | 'AnonymousTournamentParticipant'
      - `participant_id` string, uuid
      - `name` string, nullable: The name the participant renders under.
    - `side_b` AdminMatchParticipant[]
      - `id` integer
      - `participant_type` 'User' | 'AnonymousTournamentParticipant'
      - `participant_id` string, uuid
      - `name` string, nullable: The name the participant renders under.
  - `team_names` object: Each side's team name; null for a side without a team.
    - `side_a` string, nullable
    - `side_b` string, nullable
  - `game` object: The slot the match is bound to and the orders placed against it.
    - `id` integer
    - `start_time` string, date-time
    - `end_time` string, date-time
    - `arena` object, nullable
      - `id` integer
      - `name` string
      - `in_facility_id` integer
    - `order_requests` AdminOrderRequest[]
      - `id` integer
      - `type` string: HighlightRequest, ReplayRequest or ShortRequest.
      - `status` 'open' | 'in_progress' | 'in_review' | 'done' | 'archived'
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Unauthorized
- `403`: Forbidden — admin access required
- `404`: Tournament not found
- `422`: Unparseable date or unknown status; `errors[0].field` names which.

---

[API](https://skmtc.dev/hify/apis/hify-apis.md) - [All operations](https://skmtc.dev/hify/apis/hify-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/hify/apis/hify-apis/revisions/b5920403538d?raw)