Documentation / Live
Snooker API: One match as it stands: whether it is under way, the frames won, every frame known, and its latest change
One match as it stands: whether it is under way, the frames won, every frame known, and its latest change.
GEThttps://api.snookerapi.net/v1/matches/{match_id}/live
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. |
| 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. |
| 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. |
| frames_won | list | Frames won so far: player one, player two. |
| frames | list | Each frame: number, both players' points and their breaks of 50 and over. |
| winner_id | string or null | The winner's player id. |
| last_change | string or null | When the match last changed (UTC). |
| recent | list | Its latest live events, newest first. |
Example answer
A real answer, read from the data within the last hour: GET /v1/matches/mt_fse5w2by/live
{
"data": {
"id": "mt_fse5w2by",
"event": {
"id": "ev_80r2d1px",
"name": "2026 World Snooker Championship",
"season": "2025-26"
},
"stage": "main",
"round": "final",
"status": "finished",
"best_of": 35,
"player_one": {
"id": "pl_w2c64qam",
"name": "Shaun Murphy",
"score": 17
},
"player_two": {
"id": "pl_ra6m6b4g",
"name": "Wu Yize",
"score": 18
},
"frames_won": [
17,
18
],
"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
]
}
],
"winner_id": "pl_ra6m6b4g",
"last_change": "2026-10-05T11:15:09Z",
"recent": []
},
"meta": {
"plan": "House key",
"seconds_behind": 2,
"last_change": null,
"poll_seconds": 300,
"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 |