Documentation / Endpoints / Players
/v1/players/{id}/matches
A player's matches, newest first, singles and doubles.
GEThttps://api.tabletennisapi.com/v1/players/{id}/matches
Plans:LiveArchiveComplete
Parameters
| Name | In | Type | Required | What it does | Example |
|---|---|---|---|---|---|
id | path | id | required | The player id, as returned by any list | pl_51t63nz3 |
from | query | date | optional | First day (YYYY-MM-DD) | 2026-09-13 |
to | query | date | optional | Last day (YYYY-MM-DD) | 2026-09-13 |
discipline | query | string | optional | MS, WS, MD, WD, XD; teams MT, WT, XT | MS |
Run it live
GET /v1/players/{id}/matchesA real call to the API, from your browser
Your key stays in this page: it is sent only to api.tabletennisapi.com and never stored. Left empty, the call runs on a free key with its dates and fields, 20 calls a minute.
GEThttps://api.tabletennisapi.com/v1/players/{id}/matches
Not run yet
Press Run it to see the answer here.
Response
A real answer from the data, two rows shown. Every field is described in the manual.
200 OKapplication/json
{
"data": [
{
"id": "mt_fs5ttbe2",
"event": {
"id": "ev_w5hw10am",
"name": "Champions Macao 2026 Presented by Galaxy Entertainment Group"
},
"date": "2026-09-13",
"start_time": "2026-09-13T10:30:00Z",
"discipline": "WS",
"age_group": null,
"para_class": null,
"round": "final",
"round_name": "Final",
"rubber": null,
"status": "finished",
"best_of": 7,
"points_per_game": 11,
"win_by": 2,
"utc_offset_min": 480,
"sides": [
{
"side": "a",
"name": "Harimoto Miwa",
"country": "JPN",
"players": [
{
"id": "pl_51t63nz3",
"name": "Harimoto Miwa",
"country": "JPN"
}
]
},
{
"side": "b",
"name": "Chen Yi",
"country": "CHN",
"players": [
{
"id": "pl_yp1ww51h",
"name": "Chen Yi",
"country": "CHN"
}
]
}
],
"score": {
"a": 4,
"b": 3
},
"winner": "a",
"result_note": null,
"games": [
{
"a": 11,
"b": 7
},
{
"a": 11,
"b": 7
},
{
"a": 9,
"b": 11
},
{
"a": 8,
"b": 11
},
{
"a": 11,
"b": 13
},
{
"a": 11,
"b": 9
},
{
"a": 12,
"b": 10
}
],
"duration_s": 4103,
"table": 1,
"started_at": null,
"timeouts": {
"a": 1,
"b": 1
},
"cards": {
"a": [],
"b": []
},
"video_review": false,
"challenges_each": 99,
"serving": null
},
{
"id": "mt_4kejvgza",
"event": {
"id": "ev_w5hw10am",
"name": "Champions Macao 2026 Presented by Galaxy Entertainment Group"
},
"date": "2026-09-13",
"start_time": "2026-09-13T03:45:00Z",
"discipline": "WS",
"age_group": null,
"para_class": null,
"round": "semi_final",
"round_name": "Semi-finals",
"rubber": null,
"status": "finished",
"best_of": 7,
"points_per_game": 11,
"win_by": 2,
"utc_offset_min": 480,
"sides": [
{
"side": "a",
"name": "Harimoto Miwa",
"country": "JPN",
"players": [
{
"id": "pl_51t63nz3",
"name": "Harimoto Miwa",
"country": "JPN"
}
]
},
{
"side": "b",
"name": "Chen Xingtong",
"country": "CHN",
"players": [
{
"id": "pl_enrwxwqd",
"name": "Chen Xingtong",
"country": "CHN"
}
]
}
],
"score": {
"a": 4,
"b": 1
},
"winner": "a",
"result_note": null,
"games": [
{
"a": 11,
"b": 8
},
{
"a": 12,
"b": 10
},
{
"a": 6,
"b": 11
},
{
"a": 11,
"b": 9
},
{
"a": 12,
"b": 10
}
],
"duration_s": 2758,
"table": 1,
"started_at": null,
"timeouts": {
"a": 1,
"b": 1
},
"cards": {
"a": [],
"b": []
},
"video_review": false,
"challenges_each": 99,
"serving": null
}
],
"meta": {
"count": 2,
"next_cursor": "eyJvIjoyLCJwIjoyfQ",
"page": 1,
"per_page": 2,
"total": 210,
"total_pages": 105,
"next_page": 2,
"prev_page": null
}
}Example
curl
curl https://api.tabletennisapi.com/v1/players/pl_51t63nz3/matches \
-H "Authorization: Bearer $TT_KEY"Python
import os, requests res = requests.get("https://api.tabletennisapi.com/v1/players/pl_51t63nz3/matches", headers={"Authorization": "Bearer " + os.environ["TT_KEY"]}).json()
Answers come back as data and meta; errors as error. See Errors and Pagination.