---
title: "List matches for a tournament"
method: GET
path: "/v1/tournaments/{tournament_id}/matches"
tags: ["Tournament Matches"]
---

# List matches for a tournament

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

## Request

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

Returns matches for the tournament, filtered by scope, court number, and/or search term. Searches player names (including an anonymous participant's feed or linked-account name) and side team names. Results are deduplicated and ordered by sequence number.

## Query parameters

- `scope` 'past' | 'claimed' | 'unclaimed'
- `court_number` integer
- `search` string

## Response `200`

List of matches

- TournamentMatch[]
  - `id` integer
  - `game_id` integer
  - `sequence_number` integer, nullable
  - `round_number` integer, nullable
  - `stage` 'league' | 'quarterfinal' | 'semifinal' | 'knockout' | 'final' | 'third_place': Where the match sits in the tournament
  - `status` 'pending' | 'in_progress' | 'completed'
  - `status_label` 'UPCOMING' | 'LIVE' | 'DONE'
  - `winner_side` 'side_a' | 'side_b' | 'draw', nullable
  - `court_number` integer, nullable
  - `game_start_time` string, date-time, nullable
  - `game_end_time` string, date-time, nullable
  - `category_label` string, nullable: Display category, e.g. "Open Mixed Doubles"
  - `score_summary` string, nullable
  - `score_detail` object, nullable
  - `winner_names` string, nullable
  - `team_names` object: Each side's team name; null for a side without a team.
    - `side_a` string, nullable
    - `side_b` string, nullable
  - `started_at` string, date-time, nullable
  - `duration_seconds` integer, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `match_participants` object[]
    - `id` integer
    - `match_id` integer
    - `side` 'side_a' | 'side_b'
    - `participant_type` 'User' | 'AnonymousTournamentParticipant'
    - `participant_id` string
  - `match_sets` object[]
    - `id` integer
    - `match_id` integer
    - `sequence_number` integer
    - `winner_side` 'side_a' | 'side_b', nullable
    - `score` object, nullable

## Other responses

- `401`: Unauthorized
- `404`: Tournament not found

---

[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)