Documentation / Matches
Snooker API: One match, with its status, its frames where they are known (points and breaks of 50 and over), and every change to it since it entered our record
One match, with its status, its frames where they are known (points and breaks of 50 and over), and every change to it since it entered our record.
GEThttps://api.snookerapi.net/v1/matches/{match_id}
Try it
Parameters
| Name | Type | What it is |
|---|---|---|
| match_id | id, required, in the path | The match, as an mt_ id from any match list. |
Returns
| Field | Type | What it holds |
|---|---|---|
| id | string | The record's own id: stable, and the same in every call. |
| event | object | The event: id, name and season. |
| stage | string | main, qualifying or pre_qualifying. |
| round | string or null | final, semi_final, quarter_final, last_16 and so on; league or league_1 for a round robin, group_a for a group, event_1_last_round for a Q School event's deciding round; null where the article does not name it. |
| best_of | integer or null | The number of frames the match was played over. |
| player_one | object | The first player: id, name and frames won. |
| player_two | object | The second player: id, name and frames won. |
| winner_id | string or null | The winner's player id. |
| walkover | boolean | True when the match was not played. |
| date | date or null | The day it was played or made, when known. |
| played_between | object or null | The window of days when the day itself is not known: from and to. |
| date_known_to | string or null | How close the date is: day (the article's own day, or, from 28 October 2026, the day at the venue our record had the result during the event; the match's history shows which), round, stage, event or month; before_event (qualifying known only to have been played in the season before the event began) or season. |
| has_frames | boolean | Whether frame scores are held. |
| status | string | Where the match stands. A match: scheduled, in_play, finished, drawn (level at full length, as in a round-robin group), walkover, incomplete (a score but no result after its day) or unrecorded (its day passed and no score was ever published). The live match call: scheduled, live or finished. |
| record | object | How the match entered our record: first_recorded_at (when we first held it; null for matches held before 28 October 2026), result_recorded_at (when its result reached us), last_changed_at, and changes (how many changes are logged; GET /v1/matches/{match_id} lists them). |
| frames | list | Each frame: number, both players' points and their breaks of 50 and over. |
| history | list | Every change to the match since it entered our record, oldest first: at, change (added, score, result, round, date), from and to. |
Example answer
A real answer, read from the data within the last hour: GET /v1/matches/mt_fse5w2by
{
"data": {
"id": "mt_fse5w2by",
"event": {
"id": "ev_80r2d1px",
"name": "2026 World Snooker Championship",
"season": "2025-26"
},
"stage": "main",
"round": "final",
"best_of": 35,
"player_one": {
"id": "pl_w2c64qam",
"name": "Shaun Murphy",
"score": 17
},
"player_two": {
"id": "pl_ra6m6b4g",
"name": "Wu Yize",
"score": 18
},
"winner_id": "pl_ra6m6b4g",
"walkover": false,
"date": "2026-05-03",
"played_between": {
"from": "2026-05-03",
"to": "2026-05-03"
},
"date_known_to": "day",
"has_frames": true,
"status": "finished",
"record": {
"first_recorded_at": null,
"result_recorded_at": null,
"last_changed_at": "2026-10-05T11:15:09Z",
"changes": 0
},
"history": [],
"frames": [
{
"number": 1,
"points_one": 50,
"points_two": 72,
"breaks_one": [],
"breaks_two": [
51
]
},
{
"number": 2,
"points_one": 50,
"points_two": 60,
"breaks_one": [
50
],
"breaks_two": []
},
{
"number": 3,
"points_one": 53,
"points_two": 86,
"breaks_one": [],
"breaks_two": [
61
]
}
]
},
"meta": {
"plan": "House key",
"shown": "the first 3 frames of 35"
}
}Errors
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | No key, or a key that is not valid. Errors |
| 400 | bad_request | A parameter has the wrong shape. Errors |
| 422 | unknown_parameter | A parameter this call does not take. Errors |
| 429 | rate_limited | Too many calls this minute; wait for Retry-After. Errors |
| 404 | not_found | No record has that id. Errors |
| 403 | upgrade_required | The record is older than yesterday and the key is the free one. Errors |