> ## Documentation Index > Fetch the complete documentation index at: https://padelapi.org/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Player Matches > Endpoint to retrieve all matches played by a specific player with optional filters for tournament, date range, and round. ## OpenAPI ````yaml https://padelapi.org/docs/api.json get /players/{player}/matches openapi: 3.1.0 info: title: Padel API – API Reference version: '1.0' description: padelapi.org servers: - url: https://padelapi.org/api security: - http: [] paths: /players/{player}/matches: get: tags: - Player summary: List Player Matches description: >- Endpoint to retrieve all matches played by a specific player with optional filters for tournament, date range, and round. operationId: listPlayerMatches parameters: - name: player in: path required: true description: The player ID schema: type: integer - name: tournament_id in: query description: Tournament ID to filter matches by. schema: type: - integer - 'null' - name: after_date in: query description: Date after the match was played in `YYYY-MM-DD` format. schema: type: - string - 'null' format: date - name: before_date in: query description: Date before the match was played in `YYYY-MM-DD` format. schema: type: - string - 'null' format: date - name: round in: query description: >- Round of the match (1 = Final, 2 = Semifinal, 4 = Quarterfinal, 8 = Round of 16, 16 = Round of 32, 32 = Round of 64) schema: type: - integer - 'null' enum: - '1' - '2' - '4' - '8' - '16' - '32' - name: sort_by in: query description: Name of the parameter to sort the matches by. schema: type: - string - 'null' enum: - played_at - round - name: order_by in: query description: Order of the sorting, either `asc` or `desc`. schema: type: - string - 'null' enum: - asc - desc responses: '200': description: Paginated set of `MatchResource` content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/MatchResource' links: type: object properties: first: type: - string - 'null' last: type: - string - 'null' prev: type: - string - 'null' next: type: - string - 'null' required: - first - last - prev - next meta: type: object properties: current_page: type: integer from: type: - integer - 'null' last_page: type: integer links: type: array description: Generated paginator links. items: type: object properties: url: type: - string - 'null' label: type: string active: type: boolean required: - url - label - active path: type: - string - 'null' description: Base path for paginator generated URLs. per_page: type: integer description: Number of items shown per page. to: type: - integer - 'null' description: Number of the last item in the slice. total: type: integer description: Total number of items being paginated. required: - current_page - from - last_page - links - path - per_page - to - total required: - data - links - meta '401': $ref: '#/components/responses/AuthenticationException' '404': $ref: '#/components/responses/ModelNotFoundException' '422': $ref: '#/components/responses/ValidationException' components: schemas: MatchResource: type: object properties: id: type: integer description: >- Unique identifier of the match. Stable across requests, use it to reference the match from your own data. self: type: string description: Path to this match's endpoint, relative to `https://padelapi.org`. name: type: string description: >- Surnames of both teams, in the form `Surname/Surname - Surname/Surname`. Convenience label for display, not a stable identifier. url: type: - string - 'null' description: Public match page. `null` when the match has no page. category: type: string description: >- Draw the match belongs to. Men's and women's draws run in parallel at the same tournament, so pair this with `round` to place a match. enum: - men - women tournament: $ref: '#/components/schemas/TournamentResource' description: >- Tournament this match belongs to, embedded in full. Only present on MCP requests; on the REST API use `connections.tournament` instead. round: type: integer description: >- Stage of the draw as the number of matches in that round: `1` for the final, `2` semifinals, `4` quarterfinals, `8` round of 16, and so on. Lower values are later stages, so sorting ascending walks the draw backwards from the final. round_name: type: string description: >- Human-readable form of `round` (e.g. `Finals`, `Semifinals`, `Quarter`, `Round of 16`). Match on `round` rather than on this field. index: type: integer description: >- Zero-based position of the match within its round, counted from the top of the draw. Together with `round` and `category` it identifies a slot in the bracket. seeds: type: string description: >- Each team's draw marker as a string: seed number (e.g. `"1"`), or entry code (`"WC"`/`"Q"`/`"LL"`/`"ALT"`) for unseeded special entries; `null` when entered by ranking unseeded. Always a `{team_1, team_2}` object. played_at: type: - string - 'null' description: >- Day the match is played, as `YYYY-MM-DD`, in the tournament's local date. Use this for day-level filtering and `scheduled_at` for the exact time. schedule_label: type: string description: >- Human-readable form of `scheduled_at`, including how firm the time is: announced by the tournament ("Starting at 9:00 AM", "Not before 4:00 PM") or, for matches without an announced time, estimated from the court's order of play ("Estimated around 12:30 PM") and recalculated hourly. See the [schedule estimates guide](https://padelapi.org/docs/guides/match-schedule-estimates) for how estimates are built and how accurate they are. scheduled_at: type: - string - 'null' description: >- Expected start of the match in server timezone (`Europe/Madrid`), whether the time was announced by the tournament or estimated. Sort and compare on this field. scheduled_at_local: type: - string - 'null' description: >- Same instant as `scheduled_at`, serialized in the tournament's timezone. court: type: string description: >- Name of the court the match is played on, as announced by the tournament (e.g. `Centre Court`). `null` when the court has not been assigned. court_order: type: - integer - 'null' description: >- Position of the match in the order of play for its court that day, starting at `1`. Sort by this field to follow a court's schedule. `null` when the order of play has not been published. status: type: string description: >- Current state of the match. See the [statuses reference](https://padelapi.org/docs/statuses#match-statuses) for the full list, including which values are permanent and which still change. enum: - scheduled - live - ended - finished - retired - walkover - bye score: description: >- Final score of the match, as one `{team_1, team_2}` object per set played, in order. Games are strings, and a tiebreak set carries the points in parentheses (e.g. `"7(5)"`). `null` before the match has a result. On the free plan, matches played more than 6 months ago return `hidden_free_plan`; paid plans include the full historical archive. anyOf: - type: string - type: string enum: - hidden_free_plan winner: description: >- Winning team (`team_1` or `team_2`). On the free plan, matches played more than 6 months ago return `hidden_free_plan`; paid plans include the full historical archive. anyOf: - type: string - type: string enum: - hidden_free_plan started_time: type: - string - 'null' description: >- Actual start of play (first tracked point, after warm-up), in server timezone (`Europe/Madrid`). Distinct from `scheduled_at`, which is the expected start time. started_time_local: type: - string - 'null' description: >- Same instant as `started_time`, serialized in the tournament's timezone. duration: type: string description: >- Time on court as `HH:MM` (e.g. `01:25`), measured from the first tracked point to the last. `null` for matches without live tracking or still in progress. players: type: object description: >- The two pairs facing each other. `team_1` and `team_2` are fixed for the match, so `winner`, `score` and `seeds` all refer to these same keys. properties: team_1: $ref: '#/components/schemas/MatchPairResource' description: >- Players making up the first team, in no particular order. Each carries the side they play on. team_2: $ref: '#/components/schemas/MatchPairResource' description: >- Players making up the second team, in no particular order. Each carries the side they play on. required: - team_1 - team_2 updated_at: type: string description: >- ISO 8601 timestamp of the last change to any field of this match, including score and schedule. Poll on this field to pick up only what has moved, as described in the [data synchronization guide](https://padelapi.org/docs/guides/data-synchronization#matches). connections: type: string description: >- Related endpoints for this match. `prev` and `next` chain the order of play on the same court, not the progression through the draw, and are absent at either end of the day. `video` appears when there is footage, and `stats` and `live` are only present for tournaments with detailed coverage. required: - id - self - name - url - category - round - round_name - index - seeds - played_at - schedule_label - scheduled_at - scheduled_at_local - court - court_order - status - score - winner - started_time - started_time_local - duration - players - updated_at - connections title: MatchResource TournamentResource: type: object properties: id: type: integer description: >- Unique identifier of this tournament edition. A new edition of the same event gets its own `id`; use `connections.editions` to walk the history. self: type: string description: >- Path to this tournament's endpoint, relative to `https://padelapi.org`. name: type: string description: >- Official name of this edition, including the title sponsor when there is one (e.g. `Oysho Milano P1`). Sponsors change between editions, so match on `id` rather than on this field. url: type: - string - 'null' description: Public tournament page. `null` when the tournament has no page. location: type: string description: City hosting the tournament. venue: type: - object - 'null' description: >- Club or arena hosting the tournament. `null` when the venue has not been announced. properties: name: type: - string - 'null' address: type: - string - 'null' required: - name - address country: type: string description: ISO 3166-1 alpha-2 country code, uppercase. timezone: type: string description: >- IANA timezone of the venue (e.g. `Europe/Rome`). This is the timezone used to serialize the `_local` times of the tournament's matches. level: type: string description: >- Category of the tournament within its circuit. Premier Padel runs `major`, `p1`, `p2` and `finals`; the FIP Tour runs the `fip_*` levels; `wpt_*` and `ppt_*` cover the historical World Padel Tour and Padel Pro Tour. Accepted as a comma-separated filter on [`GET /tournaments`](https://padelapi.org/docs/api-reference/tournament/list-tournaments). enum: - major - p1 - p2 - finals - fip_platinum - fip_gold - fip_silver - fip_other - wpt_master - wpt_1000 - wpt_500 - wpt_final - ppt_master - ppt_final - ppt_international - ppt_promotional - ppt_other status: type: string description: >- Current state of the tournament. See the [statuses reference](https://padelapi.org/docs/statuses#tournament-statuses) for the full list and the [data synchronization guide](https://padelapi.org/docs/guides/data-synchronization#tournaments) for how to keep it up to date. enum: - pending - live - finished - cancelled court_type: description: Surface setup of the courts. `null` when it has not been announced. anyOf: - type: 'null' - type: string enum: - indoor - outdoor - covered prize: type: - object - 'null' description: >- Total prize money on offer, with `amount` as a whole unit of `currency` (ISO 4217). `null` when the tournament does not publish it. properties: amount: type: integer currency: type: string required: - amount - currency start_date: type: string description: First day of play, as `YYYY-MM-DD`. end_date: type: string description: >- Last day of play, as `YYYY-MM-DD`, normally the day the finals are played. winners: type: - object - 'null' description: >- Pairs that won the tournament, keyed by category (`men`, `women`). `null` until the tournament reaches `finished`, and a category is absent when its final has no confirmed winner. additionalProperties: $ref: '#/components/schemas/MatchPairResource' links: type: string description: >- External links related to the tournament. `null` when none are available. updated_at: type: string description: >- ISO 8601 timestamp of the last change to any field of this tournament. Use it to skip records you have already processed. connections: type: string description: >- Related endpoints for this tournament. `videos` is only present when the tournament has video content. required: - id - self - name - url - location - venue - country - timezone - level - status - court_type - prize - start_date - end_date - winners - links - updated_at - connections title: TournamentResource MatchPairResource: type: array prefixItems: - type: object properties: id: type: integer self: type: string name: type: string side: anyOf: - type: 'null' - type: string enum: - drive - backhand connections: type: string required: - id - self - name - side - connections minItems: 1 maxItems: 1 additionalItems: false title: MatchPairResource responses: AuthenticationException: description: Unauthenticated content: application/json: schema: type: object properties: message: type: string description: Error overview. required: - message ModelNotFoundException: description: Not found content: application/json: schema: type: object properties: message: type: string description: Error overview. required: - message ValidationException: description: Validation error content: application/json: schema: type: object properties: message: type: string description: Errors overview. errors: type: object description: A detailed description of each field that failed validation. additionalProperties: type: array items: type: string required: - message - errors securitySchemes: http: type: http scheme: bearer ````