Documentation / Endpoints / Events
/v1/events/{id}/matches
An event's matches, in order of play.
GEThttps://api.tabletennisapi.com/v1/events/{id}/matches
Plans:Free keyLiveArchiveComplete On the free key, games, duration_s and table come back as null
Parameters
| Name | In | Type | Required | What it does | Example |
|---|---|---|---|---|---|
id | path | id | required | The event id, as returned by any list | ev_w5hw10am |
discipline | query | string | optional | MS, WS, MD, WD, XD; teams MT, WT, XT | MS |
age_group | query | string | optional | Youth age group: U11, U13, U15, U17, U19. "senior" for seniors only | U19 |
para_class | query | string | optional | Para sport class, such as MS6 | MS6 |
round | query | string | optional | Round: final, semi_final, quarter_final, round_of_16 ... round_of_128, group, qualifying_1 to qualifying_4, qualifying_knockout or bronze | final |
status | query | string | optional | finished, live, scheduled or unconfirmed (played, no official result) | finished |
Run it live
GET /v1/events/{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/events/{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_3k4xxtgt",
"event": {
"id": "ev_w5hw10am",
"name": "Champions Macao 2026 Presented by Galaxy Entertainment Group"
},
"date": "2026-09-08",
"start_time": "2026-09-08T03:00:00Z",
"discipline": "WS",
"age_group": null,
"para_class": null,
"round": "round_of_32",
"round_name": "Round of 32",
"rubber": null,
"status": "finished",
"best_of": 5,
"points_per_game": 11,
"win_by": 2,
"utc_offset_min": 480,
"sides": [
{
"side": "a",
"name": "Chen Yi",
"country": "CHN",
"players": [
{
"id": "pl_yp1ww51h",
"name": "Chen Yi",
"country": "CHN"
}
]
},
{
"side": "b",
"name": "Yeh Yi-Tian",
"country": "TPE",
"players": [
{
"id": "pl_mpera4pm",
"name": "Yeh Yi-Tian",
"country": "TPE"
}
]
}
],
"score": {
"a": 3,
"b": 0
},
"winner": "a",
"result_note": null,
"games": [
{
"a": 11,
"b": 6
},
{
"a": 11,
"b": 8
},
{
"a": 11,
"b": 8
}
],
"duration_s": 1490,
"table": 1,
"started_at": null,
"timeouts": {
"a": 1,
"b": 1
},
"cards": {
"a": [],
"b": []
},
"video_review": false,
"challenges_each": 99,
"serving": null
},
{
"id": "mt_j4ymx6hd",
"event": {
"id": "ev_w5hw10am",
"name": "Champions Macao 2026 Presented by Galaxy Entertainment Group"
},
"date": "2026-09-08",
"start_time": "2026-09-08T03:35:00Z",
"discipline": "MS",
"age_group": null,
"para_class": null,
"round": "round_of_32",
"round_name": "Round of 32",
"rubber": null,
"status": "finished",
"best_of": 5,
"points_per_game": 11,
"win_by": 2,
"utc_offset_min": 480,
"sides": [
{
"side": "a",
"name": "Geraldo Joao",
"country": "POR",
"players": [
{
"id": "pl_b4f3t8p6",
"name": "Geraldo Joao",
"country": "POR"
}
]
},
{
"side": "b",
"name": "Lind Anders",
"country": "DEN",
"players": [
{
"id": "pl_z3jc3bsa",
"name": "Lind Anders",
"country": "DEN"
}
]
}
],
"score": {
"a": 0,
"b": 3
},
"winner": "b",
"result_note": null,
"games": [
{
"a": 5,
"b": 11
},
{
"a": 9,
"b": 11
},
{
"a": 9,
"b": 11
}
],
"duration_s": 1567,
"table": 1,
"started_at": null,
"timeouts": {
"a": 1,
"b": 1
},
"cards": {
"a": [],
"b": [
"yellow"
]
},
"video_review": false,
"challenges_each": 99,
"serving": null
}
],
"meta": {
"count": 2,
"next_cursor": "eyJvIjoyLCJwIjoyfQ",
"page": 1,
"per_page": 2,
"total": 62,
"total_pages": 31,
"next_page": 2,
"prev_page": null
}
}Example
curl
curl https://api.tabletennisapi.com/v1/events/ev_w5hw10am/matches \
-H "Authorization: Bearer $TT_KEY"Python
import os, requests res = requests.get("https://api.tabletennisapi.com/v1/events/ev_w5hw10am/matches", headers={"Authorization": "Bearer " + os.environ["TT_KEY"]}).json()
Answers come back as data and meta; errors as error. See Errors and Pagination.