tennisdatabaseAPI

Tennis API documentation

Ctrl K
DocsPlayersPlayer matches
Players

Player matches

MCP tool player_matches
GEThttps://api.tennisdatabaseapi.com/v1/players/{id}/matches

A player's matches, newest first.

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/players/pl_f560sfd7/matches?season=2026&per_page=2

1Parameters

NameInTypeWhat it is
idrequiredpathidAn id from another answer, such as pl_ and 8 characters. Ids are our own and never change.
seasonqueryyearOne season, such as 2024.
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/players/pl_f560sfd7/matches?season=2026&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_zk6sagtr",
      "date": "2026-11-15",
      "start_time": "2026-11-15T13:30: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_gh55prh0", "name": "Jodar R.", "country": "Spain" },
      "score": "6-4 6-4",
      "sets": { "winner": 2, "loser": 0 },
      "status": "completed",
      "best_of": null,
      "ranks": { "winner": 1, "loser": 11 },
      "ranking_points": { "winner": 9550, "loser": 3234 },
      "odds": {
        "closing": { "winner": 1.35, "loser": 3.19 }
      }
    }
  ],
  "meta": {
    "count": 2,
    "next_cursor": "eyJvIjoyLCJwIjoyfQ",
    "page": 1,
    "per_page": 2,
    "total": 85,
    "total_pages": 43,
    "next_page": 2,
    "prev_page": null
  }
}

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