tennisdatabaseAPI

Tennis API documentation

Ctrl K
DocsPlayersHead to head
Players

Head to head

MCP tool head_to_head
GEThttps://api.tennisdatabaseapi.com/v1/h2h/{a}/{b}

Head to head between two players.

Free key not includedLive 45 daysArchive every seasonComplete everything
Try itRuns against the live API with your key. Your key stays in this browser.API
GEThttps://api.tennisdatabaseapi.com/v1/h2h/pl_f560sfd7/pl_3vde2gfg?per_page=2

1Parameters

NameInTypeWhat it is
arequiredpathidAn id from another answer, such as pl_ and 8 characters. Ids are our own and never change.
brequiredpathidAn id from another answer, such as pl_ and 8 characters. Ids are our own and never change.
page, per_pagequeryintegerPaging: 50 a page unless you ask, at most 50. See Paging.
cursorquerystringThe meta.next_cursor of the page before, to walk a long list.

Anything else in the address answers 422 unknown_parameter, with the list of parameters this endpoint takes.

2Request

curl -H "Authorization: Bearer $TDA_KEY" \
  "https://api.tennisdatabaseapi.com/v1/h2h/pl_f560sfd7/pl_3vde2gfg?per_page=2"

The code follows the form in Try it, with your key in it once you have entered one. Without a key it reads $TDA_KEY.

3Answer

{
  "data": [
    {
      "id": "mt_m6krne7e",
      "date": "2026-11-17",
      "start_time": "2026-11-17T19:40:00Z",
      "tour": "men",
      "event_type": "singles",
      "tournament": {
        "id": "tn_6r10s9hs",
        "name": "Masters Cup ATP",
        "event_known": true,
        "tier": "tour",
        "season": 2026,
        "surface": "hard_indoor"
      },
      "round": "_",
      "winner": { "id": "pl_f560sfd7", "name": "Zverev A.", "country": "Germany" },
      "loser": { "id": "pl_3vde2gfg", "name": "Shelton B.", "country": "USA" },
      "score": "6-2 7-6(4)",
      "sets": { "winner": 2, "loser": 0 },
      "status": "completed",
      "best_of": null,
      "ranks": { "winner": 1, "loser": 4 },
      "ranking_points": { "winner": 9320, "loser": 5170 },
      "odds": {
        "closing": { "winner": 1.46, "loser": 2.7 }
      }
    },
    {
      "id": "mt_9e5aq213",
      "date": "2026-09-13",
      "start_time": "2026-09-13T18:20:00Z",
      "tour": "men",
      "event_type": "singles",
      "tournament": {
        "id": "tn_1d50xrzv",
        "name": "US Open",
        "event_known": true,
        "tier": "slam",
        "season": 2026,
        "surface": "hard"
      },
      "round": "final",
      "winner": { "id": "pl_f560sfd7", "name": "Zverev A.", "country": "Germany" },
      "loser": { "id": "pl_3vde2gfg", "name": "Shelton B.", "country": "USA" },
      "score": "6-3 7-6(2) 5-7 6-2",
      "sets": { "winner": 3, "loser": 1 },
      "status": "completed",
      "best_of": 5,
      "ranks": { "winner": 2, "loser": 9 },
      "ranking_points": { "winner": 7790, "loser": 3480 },
      "odds": {
        "closing": { "winner": 1.67, "loser": 2.2 }
      }
    }
  ],
  "meta": {
    "count": 2,
    "next_cursor": "eyJvIjoyLCJwIjoyfQ",
    "page": 1,
    "per_page": 2,
    "total": 7,
    "total_pages": 4,
    "next_page": 2,
    "prev_page": null,
    "wins": { "pl_f560sfd7": 7, "pl_3vde2gfg": 0 }
  }
}

Real answers from the API, made 2026-11-18. Long lists are cut to three items here.

A field your plan does not include is still there, as null, so code written on the free key keeps working after an upgrade. meta.held_back names what was held back and meta.note the plan that adds it.

4Fields

FieldTypeWhat it holdsFree key
idstringThe match id, mt_ and 8 charactersincluded
datedateThe day it was played, UTCincluded
start_timedatetimeWhen play began (or is set to begin) on the match's date, UTC, as listed for that day; for a match finished on a later day, the time it resumed that day; null where not knownincluded
tournamentobjectid, name, event_known, tier, season, surfaceincluded
roundstringfinal, semi_final, quarter_final, round_of_16, round_1, qualifying and so onincluded
winner, loserobjectid, name, countryincluded
scorestringThe score from the winner's side, tie-breaks in bracketsincluded
setsobjectSets won by the winner and the loserincluded
statusstringcompleted, retired, walkover or defaultedincluded
best_ofinteger3 or 5included
ranksobjectEach player's ranking on the day, where knownincluded
ranking_pointsobjectEach player's ranking points on the day, where known (from the same weekly list as the ranking)included
odds.closingobjectThe market's closing prices for the winner and the loser, decimalnull

5Errors

400bad_requestA value out of range, such as a date or a tier that is not one of the list.
401unauthorizedNo key, or a key that is unknown or revoked.
403upgrade_requiredThe free key: this endpoint is on the Live plan and above.
404not_foundNo such id.
422unknown_parameterA parameter this endpoint does not take.
429rate_limitedToo many calls this minute, or the allowance used (quota_exceeded).