GET
https://api.tennisdatabaseapi.com/v1/tournaments/{id}/{season}Paid plansEvery 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
| Name | What it is |
|---|---|
idrequired | An id from another answer, such as tn_ and 8 characters. Ids are our own and never change. |
seasonrequired | A season, such as 2024. |
page, per_page | Paging: 50 a page unless you ask, at most 50. See Paging. |
cursor | The 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"
$ch = curl_init('https://api.tennisdatabaseapi.com/v1/tournaments/tn_1d50xrzv/2026?per_page=2'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TDA_KEY')], CURLOPT_RETURNTRANSFER => true, ]); $answer = json_decode(curl_exec($ch), true); print_r($answer['data']);
import os, requests r = requests.get( "https://api.tennisdatabaseapi.com/v1/tournaments/tn_1d50xrzv/2026?per_page=2", headers={"Authorization": f"Bearer {os.environ['TDA_KEY']}"}, ) print(r.json()["data"])
const r = await fetch("https://api.tennisdatabaseapi.com/v1/tournaments/tn_1d50xrzv/2026?per_page=2", { headers: { Authorization: `Bearer ${process.env.TDA_KEY}` }, }); const { data } = await r.json(); console.log(data);
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
}
}{
"error": {
"code": "upgrade_required",
"message": "This endpoint is on the Live plan and above.",
"plan": "Live",
"upgrade": "https://tennisdatabaseapi.com/pricing",
"docs": "https://tennisdatabaseapi.com/documentation/errors"
}
}{
"error": {
"code": "not_found",
"message": "No such season of this tournament.",
"docs": "https://tennisdatabaseapi.com/documentation/errors"
}
}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
| Field | What it holds |
|---|---|
id | The match id, mt_ and 8 characters |
date | The day it was played, UTC |
start_time | When 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 known |
tournament | id, name, event_known, tier, season, surface |
round | final, semi_final, quarter_final, round_of_16, round_1, qualifying and so on |
winner, loser | id, name, country |
score | The score from the winner's side, tie-breaks in brackets |
sets | Sets won by the winner and the loser |
status | completed, retired, walkover or defaulted |
best_of | 3 or 5 |
ranks | Each player's ranking on the day, where known |
ranking_points | Each player's ranking points on the day, where known (from the same weekly list as the ranking) |
odds.closing | The market's closing prices for the winner and the loser, decimal |
5Errors
bad_request | A value out of range, such as a date or a tier that is not one of the list. |
unauthorized | No key, or a key that is unknown or revoked. |
upgrade_required | The free key: this endpoint is on the Live plan and above. |
not_found | No such id, or no such season of this tournament. |
unknown_parameter | A parameter this endpoint does not take. |
rate_limited | Too many calls this minute, or the allowance used (quota_exceeded). |