Head-to-head
get_h2hThe all-time record between two players, across BOTH halves of the product. That is the results archive (1968 to 2022) plus the completed matches from 2023 onward. Names are the keys. An ambiguous fragment returns the candidate list to choose from, and nothing is guessed. Totals count only meetings with a known winner. Walkovers and retirements are part of the record, and each meeting carries its outcome. Requires the BASIC plan or any History plan.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"player1": "<player1>",
"player2": "<player2>"
},
"name": "get_h2h"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| player1 | Yes | First player name (fragment, min 3 chars), e.g. "federer". | |
| player2 | Yes | Second player name (fragment, min 3 chars), e.g. "nadal". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | True when the request succeeded, including when the answer is an empty list. False for a missing or rejected key, a plan that does not include this data, an unknown id, a rate limit or a network error. The message then says what to do. check_api_status is the exception: it is true whenever the API answered, and reports API key problems in the message. | |
| totals | No | The headline record. | |
| message | Yes | Human-readable summary of the result, safe to relay to the user verbatim. | |
| players | No | The resolved names. Null when no player matches the fragments. | |
| meetings | No | Individual meetings, newest first, capped at 200. | |
| by_surface | No | Decided wins per surface. The keys are surface names plus "unknown". |