tennisdatabaseAPI

Tennis API documentation

Ctrl K
DocsTournamentsTournament season
Tournaments

Tournament season

MCP tool tournament_results
GEThttps://api.tennisdatabaseapi.com/v1/tournaments/{id}/{season}

Every match of one season of a tournament.

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/tournaments/tn_1d50xrzv/2026?per_page=2

1Parameters

NameInTypeWhat it is
idrequiredpathidAn id from another answer, such as tn_ and 8 characters. Ids are our own and never change.
seasonrequiredpathyearA 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/tournaments/tn_1d50xrzv/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_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 }
      }
    },
    {
      "id": "mt_qvs9vycz",
      "date": "2026-09-12",
      "start_time": "2026-09-11T23:45:00Z",
      "tour": "men",
      "event_type": "singles",
      "tournament": {
        "id": "tn_1d50xrzv",
        "name": "US Open",
        "event_known": true,
        "tier": "slam",
        "season": 2026,
        "surface": "hard"
      },
      "round": "semi_final",
      "winner": { "id": "pl_3vde2gfg", "name": "Shelton B.", "country": "USA" },
      "loser": { "id": "pl_9phm72a9", "name": "Tiafoe F.", "country": "USA" },
      "score": "4-6 6-3 6-3 7-5",
      "sets": { "winner": 3, "loser": 1 },
      "status": "completed",
      "best_of": 5,
      "ranks": { "winner": 9, "loser": 12 },
      "ranking_points": { "winner": 3480, "loser": 2680 },
      "odds": {
        "closing": { "winner": 1.34, "loser": 3.19 }
      }
    }
  ],
  "meta": {
    "count": 2,
    "next_cursor": "eyJvIjoyLCJwIjoyfQ",
    "page": 1,
    "per_page": 2,
    "total": 239,
    "total_pages": 120,
    "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, or no such season of this tournament.
422unknown_parameterA parameter this endpoint does not take.
429rate_limitedToo many calls this minute, or the allowance used (quota_exceeded).