GET /matchesFree key, archive on paidMCP: find_matches

Snooker API: Matches: results and draws, newest first, by event, player, season or dates

Matches: results and draws, newest first, by event, player, season or dates.

GEThttps://api.snookerapi.net/v1/matches

Try it

event_idplayer_idseasonstageroundfromtostatuspagecursorper_page

Parameters

Name	Type	What it is
event_id	id	Only this event (ev_ id).
player_id	id	Only this player's matches (pl_ id).
season	season	Season, e.g. 2025-26.
stage	string	Main draw or qualifying. main qualifying pre_qualifying
round	string	Round, e.g. final, semi_final, quarter_final, last_16; 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.
from	date	Played on or after this day.
to	date	Played on or before this day.
status	string	Only matches in this state: scheduled, in_play, finished, drawn, walkover, incomplete (a score but no result after its day) or unrecorded (its day passed with no score published). scheduled in_play finished drawn walkover incomplete unrecorded
page	integer	Page number, from 1.
cursor	string	The next_cursor from the previous page.
per_page	integer	Rows per page.

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).

Example answer

A real answer, read from the data within the last hour: GET /v1/matches?event_id=ev_80r2d1px&round=final

{
    "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
            }
        }
    ],
    "meta": {
        "plan": "House key",
        "count": 1,
        "next_cursor": null,
        "page": 1,
        "per_page": 50,
        "total": 1,
        "total_pages": 1,
        "next_page": null,
        "prev_page": null
    }
}

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

PreviousGET /v1/events/{event_id}/points NextGET /v1/matches/{match_id}