Documentation / Players
Snooker API: Two players' meetings: how many, who won, frames won by each, their finals, and every match between them, newest first
Two players' meetings: how many, who won, frames won by each, their finals, and every match between them, newest first.
GEThttps://api.snookerapi.net/v1/head-to-head
Try it
Parameters
| Name | Type | What it is |
|---|---|---|
| player_a | id, required | One player (pl_ id). |
| player_b | id, required | The other player (pl_ id). |
| 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 |
|---|---|---|
| player_a | object | The first player: id and name. |
| player_b | object | The second player: id and name. |
| meetings | integer | How many times the two have met. |
| wins_a | integer | Meetings won by player_a. |
| wins_b | integer | Meetings won by player_b. |
| frames_a | integer | Frames player_a won in their meetings (where the score is in frames). |
| frames_b | integer | Frames player_b won in their meetings. |
| finals | integer | How many of their meetings were main-draw finals. |
| last_meeting | object or null | The newest meeting, as in the matches list. |
| matches | integer | How many matches are held. |
Example answer
A real answer, read from the data within the last hour: GET /v1/head-to-head?player_a=pl_ra6m6b4g&player_b=pl_w2c64qam&per_page=3
{
"data": {
"player_a": {
"id": "pl_ra6m6b4g",
"name": "Wu Yize"
},
"player_b": {
"id": "pl_w2c64qam",
"name": "Shaun Murphy"
},
"meetings": 5,
"wins_a": 4,
"wins_b": 1,
"frames_a": 39,
"frames_b": 33,
"finals": 1,
"last_meeting": {
"id": "mt_pzdj9mgg",
"event": {
"id": "ev_zr3zkbe3",
"name": "2026 Shenzhen Open",
"season": "2026-27"
},
"stage": "main",
"round": "quarter_final",
"best_of": 9,
"player_one": {
"id": "pl_w2c64qam",
"name": "Shaun Murphy",
"score": 4
},
"player_two": {
"id": "pl_ra6m6b4g",
"name": "Wu Yize",
"score": 5
},
"winner_id": "pl_ra6m6b4g",
"walkover": false,
"date": "2026-10-02",
"played_between": {
"from": "2026-10-02",
"to": "2026-10-02"
},
"date_known_to": "round",
"has_frames": false,
"status": "finished",
"record": {
"first_recorded_at": null,
"result_recorded_at": null,
"last_changed_at": "2026-10-05T10:51:54Z",
"changes": 0
}
},
"matches": [
{
"id": "mt_pzdj9mgg",
"event": {
"id": "ev_zr3zkbe3",
"name": "2026 Shenzhen Open",
"season": "2026-27"
},
"stage": "main",
"round": "quarter_final",
"best_of": 9,
"player_one": {
"id": "pl_w2c64qam",
"name": "Shaun Murphy",
"score": 4
},
"player_two": {
"id": "pl_ra6m6b4g",
"name": "Wu Yize",
"score": 5
},
"winner_id": "pl_ra6m6b4g",
"walkover": false,
"date": "2026-10-02",
"played_between": {
"from": "2026-10-02",
"to": "2026-10-02"
},
"date_known_to": "round",
"has_frames": false,
"status": "finished",
"record": {
"first_recorded_at": null,
"result_recorded_at": null,
"last_changed_at": "2026-10-05T10:51:54Z",
"changes": 0
}
},
{
"id": "mt_bvqnphbw",
"event": {
"id": "ev_tbkgjcj9",
"name": "2026 Shanghai Masters",
"season": "2026-27"
},
"stage": "main",
"round": "quarter_final",
"best_of": 11,
"player_one": {
"id": "pl_w2c64qam",
"name": "Shaun Murphy",
"score": 5
},
"player_two": {
"id": "pl_ra6m6b4g",
"name": "Wu Yize",
"score": 6
},
"winner_id": "pl_ra6m6b4g",
"walkover": false,
"date": null,
"played_between": {
"from": "2026-07-27",
"to": "2026-08-02"
},
"date_known_to": "event",
"has_frames": false,
"status": "finished",
"record": {
"first_recorded_at": null,
"result_recorded_at": null,
"last_changed_at": "2026-10-05T10:51:56Z",
"changes": 0
}
},
{
"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": 3,
"next_cursor": "bzMuYjc3MjM0",
"page": 1,
"per_page": 3,
"total": 5,
"total_pages": 2,
"next_page": 2,
"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 |