Documentation / Endpoints / Matches
/v1/matches
Matches on a day or across dates, every event.
GEThttps://api.tabletennisapi.com/v1/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 |
|---|---|---|---|---|---|
date | query | date | optional | One day (YYYY-MM-DD), the local day of play. Default: today | 2026-09-13 |
from | query | date | optional | First day, with to | 2026-09-13 |
to | query | date | optional | Last day, with from (at most 31 days) | 2026-09-13 |
discipline | query | string | optional | MS, WS, MD, WD, XD; teams MT, WT, XT | MS |
age_group | query | string | optional | Youth age group: U11 to U19. "senior" for seniors only | U19 |
tier | query | int | optional | Event tier, 1 to 5 | 1 |
status | query | string | optional | finished, live, scheduled or unconfirmed (played, no official result) | finished |
country | query | string | optional | Matches with a player from this country (three letters) | CHN |
Run it live
GET /v1/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/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_6twqf194",
"event": {
"id": "ev_w5hw10am",
"name": "Champions Macao 2026 Presented by Galaxy Entertainment Group"
},
"date": "2026-09-13",
"start_time": "2026-09-13T03:00: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": "Hayata Hina",
"country": "JPN",
"players": [
{
"id": "pl_awb8xnz2",
"name": "Hayata Hina",
"country": "JPN"
}
]
},
{
"side": "b",
"name": "Chen Yi",
"country": "CHN",
"players": [
{
"id": "pl_yp1ww51h",
"name": "Chen Yi",
"country": "CHN"
}
]
}
],
"score": {
"a": 3,
"b": 4
},
"winner": "b",
"result_note": null,
"games": [
{
"a": 4,
"b": 11
},
{
"a": 6,
"b": 11
},
{
"a": 11,
"b": 8
},
{
"a": 8,
"b": 11
},
{
"a": 11,
"b": 8
},
{
"a": 18,
"b": 16
},
{
"a": 4,
"b": 11
}
],
"duration_s": 4067,
"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": 10,
"total_pages": 5,
"next_page": 2,
"prev_page": null
}
}Example
curl
curl https://api.tabletennisapi.com/v1/matches \
-H "Authorization: Bearer $TT_KEY"Python
import os, requests res = requests.get("https://api.tabletennisapi.com/v1/matches", headers={"Authorization": "Bearer " + os.environ["TT_KEY"]}).json()
Answers come back as data and meta; errors as error. See Errors and Pagination.