Matches endpoints

Live scoreboards, completed results, upcoming fixtures, the full match archive and per-match stats.

/tennis/matches · Query Match Archive
/tennis/matches/completed · Completed Matches for a Day
/tennis/matches/live · List Active Live Matches
/tennis/matches/live/{match_id} · Get Detailed Live Match State
/tennis/matches/recent · Get Recent Tour Matches
/tennis/matches/upcoming · Upcoming Scheduled Matches
/tennis/matches/{match_id} · Get Match Details & Box Score
/tennis/matches/{match_id}/stats · Match Statistics Slice
/tennis/matches/{match_id}/status · Unified Match Status
/tennis/matches/{match_id}/timeline · Completed Match Timeline
/tennis/matches/{match_id}/tournament-link · Resolve a Match Id to Its Tournament (Any Id Dialect)
/tennis/schedule · Daily Tennis Schedule

GET/tennis/matches

Query Match Archive

Retrieves paginated match history with flexible filters.

Parameter	In	Type	Description
player_id	query	string	Matches involving this player
opponent_id	query	string	Matches against this opponent
tour	query	string	Tour: ATP or WTA
year	query	integer	Calendar year
date_start	query	string	Start date (YYYY-MM-DD)
date_end	query	string	End date (YYYY-MM-DD)
date	query	string	Single day (YYYY-MM-DD); same as date_start=date_end
from	query	string	Alias for date_start
to	query	string	Alias for date_end
surface	query	string	Surface: Hard, Clay, Grass, Carpet
tournament_id	query	string	Specific tournament ID
round	query	string	Round code: F, SF, QF, R16, R32, R64, R128, RR, Q, Q1, Q2, Q3, BR, ER. Prose forms ('Final', 'Round of 32') are accepted too
level	query	string	Level: G, M, A, F, D, C, itf, junior, or an ITF prize level (15, 25, M25, W100)
page	query	integer	Page number (1-indexed)min 1 · default 1
page_size	query	integer	Items per pagemin 1 · max 100 · default 20
limit	query	integer	Alias for page_sizemin 1 · max 100

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches?player_id=atp_206173&surface=Grass&page_size=2"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "id": "s365_2026_4764920",
      "tournament_id": "atp_2026_540",
      "tournament_name": "Wimbledon",
      "year": 2026,
      "match_date": "2026-07-12",
      "tour": "ATP",
      "surface": "Grass",
      "level": "G",
      "category": "grand_slam",
      "round": "F",
      "round_name": "Final",
      "best_of": 5,
      "score": "6-7 7-6 6-3 6-4",
      "outcome": "COMPLETED",
      "status": "COMPLETED",
      "duration_minutes": null,
      "winner_id": "atp_206173",
      "loser_id": "atp_100644",
      "winner": {
        "id": "atp_206173",
        "name": "Jannik Sinner",
        "ioc": "ITA",
        "seed": "1",
        "entry": null,
        "rank": 1,
        "is_winner": true
      },
      "loser": {
        "id": "atp_100644",
        "name": "Alexander Zverev",
        "ioc": "GER",
        "seed": "2",
        "entry": null,
        "rank": 3,
        "is_winner": false
      },
      "player1": {
        "id": "atp_206173",
        "name": "Jannik Sinner",
        "ioc": "ITA",
        "seed": "1",
        "entry": null,
        "rank": 1,
        "is_winner": true
      },
      "player2": {
        "id": "atp_100644",
        "name": "Alexander Zverev",
        "ioc": "GER",
        "seed": "2",
        "entry": null,
        "rank": 3,
        "is_winner": false
      },
      "sets": [],
      "name": "Wimbledon",
      "starts_at": "2026-07-12T00:00:00+00:00"
    },
    {
      "id": "s365_2026_4762041",
      "tournament_id": "atp_2026_540",
      "tournament_name": "Wimbledon",
      "year": 2026,
      "match_date": "2026-07-10",
      "tour": "ATP",
      "surface": "Grass",
      "level": "G",
      "category": "grand_slam",
      "round": "SF",
      "round_name": "Semi-Finals",
      "best_of": 5,
      "score": "6-4 6-4 6-4",
      "outcome": "COMPLETED",
      "status": "COMPLETED",
      "duration_minutes": null,
      "winner_id": "atp_206173",
      "loser_id": "atp_104925",
      "winner": {
        "id": "atp_206173",
        "name": "Jannik Sinner",
        "ioc": "ITA",
        "seed": "1",
        "entry": null,
        "rank": 1,
        "is_winner": true
      },
      "loser": {
        "id": "atp_104925",
        "name": "Novak Djokovic",
        "ioc": "SRB",
        "seed": "7",
        "entry": null,
        "rank": 7,
        "is_winner": false
      },
      "player1": {
        "id": "atp_206173",
        "name": "Jannik Sinner",
        "ioc": "ITA",
        "seed": "1",
        "entry": null,
        "rank": 1,
        "is_winner": true
      },
      "player2": {
        "id": "atp_104925",
        "name": "Novak Djokovic",
        "ioc": "SRB",
        "seed": "7",
        "entry": null,
        "rank": 7,
        "is_winner": false
      },
      "sets": [],
      "name": "Wimbledon",
      "starts_at": "2026-07-10T00:00:00+00:00"
    }
  ],
  "total": 50,
  "page": 1,
  "page_size": 2,
  "total_pages": 25,
  "has_next": true,
  "has_prev": false
}

GET/tennis/matches/completed

Completed Matches for a Day

Returns finalised ATP/WTA match records for one calendar day.

This is the convenient daily-results endpoint; use ``/matches`` for broader archive filters. Dates use the source match date rather than request-local time.

Parameter	In	Type	Description
date*	query	string	Match date in YYYY-MM-DD (UTC match date)
tour	query	string	Optional tour filter: ATP or WTA
level	query	string	Optional tournament level filter
page	query	integer	Page number (1-indexed)min 1 · default 1
page_size	query	integer	Items per pagemin 1 · max 500 · default 50

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/completed?date=2026-10-01&page_size=2"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "id": "fs_MXtssb2T",
      "tournament_id": "fs_atp_2026_m15-telavi-2",
      "tournament_name": "M15 Telavi 2",
      "year": 2026,
      "match_date": "2026-10-01",
      "tour": "ATP",
      "surface": "Clay",
      "level": "15",
      "category": "itf",
      "round": "QF",
      "round_name": "Quarter-Finals",
      "best_of": 3,
      "score": "6-3 6-3",
      "outcome": "COMPLETED",
      "status": "COMPLETED",
      "duration_minutes": null,
      "winner_id": "atp_210174",
      "loser_id": "atp_206580",
      "winner": {
        "id": "atp_210174",
        "name": "Matic Dimic",
        "ioc": "SLO",
        "seed": null,
        "entry": null,
        "rank": 1911,
        "is_winner": true
      },
      "loser": {
        "id": "atp_206580",
        "name": "Nicola Rispoli",
        "ioc": "ITA",
        "seed": null,
        "entry": null,
        "rank": 1223,
        "is_winner": false
      },
      "player1": {
        "id": "atp_210174",
        "name": "Matic Dimic",
        "ioc": "SLO",
        "seed": null,
        "entry": null,
        "rank": 1911,
        "is_winner": true
      },
      "player2": {
        "id": "atp_206580",
        "name": "Nicola Rispoli",
        "ioc": "ITA",
        "seed": null,
        "entry": null,
        "rank": 1223,
        "is_winner": false
      },
      "sets": [],
      "name": "M15 Telavi 2",
      "starts_at": "2026-10-01T00:00:00+00:00"
    },
    {
      "id": "fs_E7wZrKXG",
      "tournament_id": "fs_atp_2026_m15-telavi-2",
      "tournament_name": "M15 Telavi 2",
      "year": 2026,
      "match_date": "2026-10-01",
      "tour": "ATP",
      "surface": "Clay",
      "level": "15",
      "category": "itf",
      "round": "QF",
      "round_name": "Quarter-Finals",
      "best_of": 3,
      "score": "6-4 3-6 6-2",
      "outcome": "COMPLETED",
      "status": "COMPLETED",
      "duration_minutes": null,
      "winner_id": "atp_212311",
      "loser_id": "atp_208152",
      "winner": {
        "id": "atp_212311",
        "name": "Stijn Paardekooper",
        "ioc": "NED",
        "seed": null,
        "entry": null,
        "rank": 958,
        "is_winner": true
      },
      "loser": {
        "id": "atp_208152",
        "name": "Gabriele Bosio",
        "ioc": "ITA",
        "seed": null,
        "entry": null,
        "rank": 634,
        "is_winner": false
      },
      "player1": {
        "id": "atp_212311",
        "name": "Stijn Paardekooper",
        "ioc": "NED",
        "seed": null,
        "entry": null,
        "rank": 958,
        "is_winner": true
      },
      "player2": {
        "id": "atp_208152",
        "name": "Gabriele Bosio",
        "ioc": "ITA",
        "seed": null,
        "entry": null,
        "rank": 634,
        "is_winner": false
      },
      "sets": [],
      "name": "M15 Telavi 2",
      "starts_at": "2026-10-01T00:00:00+00:00"
    }
  ],
  "total": 253,
  "page": 1,
  "page_size": 2,
  "total_pages": 127,
  "has_next": true,
  "has_prev": false
}

GET/tennis/matches/live

List Active Live Matches

Retrieves all currently active in-progress tennis matches with live scores.

Parameter	In	Type	Description
limit	query	integer	Max live matches to returnmin 1 · max 500
page_size	query	integer	Alias for limitmin 1 · max 500

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/live"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "id": "s365_4869062",
      "match_id": "s365_4869062",
      "started_at": "2026-10-02T21:52:22.579110+00:00",
      "round_name": "Round not specified by the source",
      "tour": "ATP",
      "tournament_id": null,
      "tournament_name": "Challenger-D, Curitiba",
      "court": "Quadra Central",
      "surface": "Hard",
      "round": "ER",
      "best_of": 3,
      "status": "IN_PROGRESS",
      "outcome": null,
      "player1": {
        "id": null,
        "name": "Boris Arias/Ignacio Carou",
        "ioc": null,
        "seed": null,
        "sets_won": 0,
        "current_game_score": "30",
        "is_serving": true
      },
      "player2": {
        "id": null,
        "name": "Miguel L G./Ribeiro E.",
        "ioc": null,
        "seed": null,
        "sets_won": 1,
        "current_game_score": "40",
        "is_serving": false
      },
      "winner": null,
      "loser": null,
      "winner_side": null,
      "current_set": 2,
      "game_score": "30-40",
      "server": 1,
      "sets": [
        {
          "set_num": 1,
          "set_number": 1,
          "score": "4-6",
          "player1_games": 4,
          "player2_games": 6,
          "tiebreak": null,
          "is_completed": true
        },
        {
          "set_num": 2,
          "set_number": 2,
          "score": "4-5",
          "player1_games": 4,
          "player2_games": 5,
          "tiebreak": null,
          "is_completed": false
        }
      ],
      "stats": [
        {
          "name": "Aces",
          "side": 1,
          "value": "1",
          "category": "Serves"
        },
        {
          "name": "Break Points Won",
          "side": 1,
          "value": "0/2 (0%)",
          "category": "Returns"
        }
      ],
      "name": "Challenger-D, Curitiba",
      "starts_at": "2026-10-02T21:52:22.579110+00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1,
  "total_pages": 1,
  "has_next": false,
  "has_prev": false
}

GET/tennis/matches/live/{match_id}

Get Detailed Live Match State

Retrieves real-time score, point history, and server for an active match.

Parameter	In	Type	Description
match_id*	path	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/live/s365_4869062"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "id": "s365_4869062",
  "match_id": "s365_4869062",
  "started_at": null,
  "round_name": "Round not specified by the source",
  "tour": "ATP",
  "tournament_id": null,
  "tournament_name": "Challenger-D, Curitiba",
  "court": "Quadra Central",
  "best_of": 3,
  "round": "ER",
  "surface": "Hard",
  "status": "IN_PROGRESS",
  "player1": {
    "id": null,
    "name": "Boris Arias/Ignacio Carou",
    "ioc": null,
    "seed": null,
    "sets_won": 0,
    "current_game_score": "30",
    "is_serving": true
  },
  "player2": {
    "id": null,
    "name": "Miguel L G./Ribeiro E.",
    "ioc": null,
    "seed": null,
    "sets_won": 1,
    "current_game_score": "40",
    "is_serving": false
  },
  "winner_side": null,
  "current_set": 2,
  "game_score": "30-40",
  "server": 1,
  "tiebreak_score": null,
  "sets": [
    {
      "set_num": 1,
      "set_number": 1,
      "score": "4-6",
      "player1_games": 4,
      "player2_games": 6,
      "tiebreak": null,
      "is_completed": true
    },
    {
      "set_num": 2,
      "set_number": 2,
      "score": "4-5",
      "player1_games": 4,
      "player2_games": 5,
      "tiebreak": null,
      "is_completed": false
    }
  ],
  "point_history": [
    {
      "num": 1,
      "score": "0-15",
      "winner": 2
    },
    {
      "num": 2,
      "score": "15-15",
      "winner": 1
    }
  ],
  "stats": [
    {
      "name": "Aces",
      "side": 1,
      "value": "1",
      "category": "Serves"
    },
    {
      "name": "Break Points Won",
      "side": 1,
      "value": "0/2 (0%)",
      "category": "Returns"
    }
  ],
  "name": "Challenger-D, Curitiba"
}

GET/tennis/matches/recent

Get Recent Tour Matches

Retrieves recent completed matches.

Parameter	In	Type	Description
tour	query	string	ATP or WTA
level	query	string	Level
limit	query	integer	Limit countmin 1 · max 500 · default 20
page_size	query	integer	Alias for limit, matching the paginated routesmin 1 · max 500

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/recent?page_size=2"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "id": "fs_fsg0uyeM",
      "tournament_id": "fs_wta_2026_w15-trelew",
      "tournament_name": "W15 Trelew",
      "match_date": "2026-10-02",
      "tour": "WTA",
      "surface": "Hard",
      "round": "QF",
      "score": "5-7 6-3 6-3",
      "outcome": "COMPLETED",
      "status": "COMPLETED",
      "winner_id": "wta_220447",
      "loser_id": "wta_270329",
      "winner": {
        "id": "wta_220447",
        "name": "Maria Florencia Urrutia"
      },
      "loser": {
        "id": "wta_270329",
        "name": "Emily Zornada"
      },
      "player1": {
        "id": "wta_220447",
        "name": "Maria Florencia Urrutia"
      },
      "player2": {
        "id": "wta_270329",
        "name": "Emily Zornada"
      },
      "sets": [
        {
          "set_number": 1,
          "winner_games": 5,
          "loser_games": 7,
          "player1_games": 5,
          "player2_games": 7,
          "tiebreak": null
        },
        {
          "set_number": 2,
          "winner_games": 6,
          "loser_games": 3,
          "player1_games": 6,
          "player2_games": 3,
          "tiebreak": null
        }
      ],
      "name": "W15 Trelew",
      "starts_at": "2026-10-02T00:00:00+00:00"
    },
    {
      "id": "fs_UgvJupk5",
      "tournament_id": "fs_atp_2026_m15-fayetteville-ar",
      "tournament_name": "M15 Fayetteville, AR",
      "match_date": "2026-10-02",
      "tour": "ATP",
      "surface": "Hard",
      "round": "QF",
      "score": "6-1 3-6 7-5",
      "outcome": "COMPLETED",
      "status": "COMPLETED",
      "winner_id": "atp_210494",
      "loser_id": "atp_211325",
      "winner": {
        "id": "atp_210494",
        "name": "Theo Papamalamis"
      },
      "loser": {
        "id": "atp_211325",
        "name": "Aryan Shah"
      },
      "player1": {
        "id": "atp_210494",
        "name": "Theo Papamalamis"
      },
      "player2": {
        "id": "atp_211325",
        "name": "Aryan Shah"
      },
      "sets": [
        {
          "set_number": 1,
          "winner_games": 6,
          "loser_games": 1,
          "player1_games": 6,
          "player2_games": 1,
          "tiebreak": null
        },
        {
          "set_number": 2,
          "winner_games": 3,
          "loser_games": 6,
          "player1_games": 3,
          "player2_games": 6,
          "tiebreak": null
        }
      ],
      "name": "M15 Fayetteville, AR",
      "starts_at": "2026-10-02T00:00:00+00:00"
    }
  ],
  "total": 5512,
  "page": 1,
  "page_size": 2,
  "total_pages": 2756,
  "has_next": true,
  "has_prev": false
}

GET/tennis/matches/upcoming

Upcoming Scheduled Matches

Scheduled fixtures for the next ~3 days, soonest first.

Fed by the same source as the live board; a fixture keeps its match_id when it goes live, so ids are stable across upcoming -> live -> finished.

Parameter	In	Type	Description
limit	query	integer	Max fixtures to returnmin 1 · max 500 · default 100
page_size	query	integer	Alias for limitmin 1 · max 500
tour	query	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/upcoming?page_size=2"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "items": [
    {
      "match_id": "s365_4868574",
      "id": "s365_4868574",
      "status": "SCHEDULED",
      "outcome": null,
      "scheduled_at": "2026-10-03T02:00:00+00:00",
      "tour": "ATP",
      "tournament_id": null,
      "tournament_name": "Tokyo - Round of 16",
      "round": "R16",
      "round_name": "Round of 16",
      "surface": "Hard",
      "player1": {
        "id": "atp_133430",
        "name": "Denis Shapovalov",
        "ioc": "CAN"
      },
      "player2": {
        "id": "atp_126214",
        "name": "Alejandro Tabilo",
        "ioc": "CHI"
      },
      "winner": null,
      "loser": null,
      "sets": [],
      "name": "Tokyo - Round of 16",
      "starts_at": "2026-10-03T02:00:00+00:00"
    },
    {
      "match_id": "s365_4868380",
      "id": "s365_4868380",
      "status": "SCHEDULED",
      "outcome": null,
      "scheduled_at": "2026-10-03T03:00:00+00:00",
      "tour": "WTA",
      "tournament_id": null,
      "tournament_name": "Beijing - 2nd Round",
      "round": "2nd Round",
      "round_name": "2nd Round",
      "surface": "Hard",
      "player1": {
        "id": "wta_220465",
        "name": "Katie Volynets",
        "ioc": "USA"
      },
      "player2": {
        "id": "wta_210722",
        "name": "Elise Mertens",
        "ioc": "BEL"
      },
      "winner": null,
      "loser": null,
      "sets": [],
      "name": "Beijing - 2nd Round",
      "starts_at": "2026-10-03T03:00:00+00:00"
    }
  ],
  "total": 50,
  "page": 1,
  "page_size": 2,
  "total_pages": 25,
  "has_next": true,
  "has_prev": false
}

GET/tennis/matches/{match_id}

Get Match Details & Box Score

Retrieves full match score, set breakdown, and match serving/return stats.

Parameter	In	Type	Description
match_id*	path	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/s365_2026_4866705"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "id": "s365_2026_4866705",
  "tournament_id": "s365_wta_2026_live-wta-125k-jingshan",
  "tournament": {
    "id": "s365_wta_2026_live-wta-125k-jingshan",
    "name": "WTA 125K, Jingshan",
    "year": 2026,
    "surface": "Hard",
    "level": "A",
    "category": "wta_tour",
    "city": null,
    "country": null
  },
  "match_date": "2026-10-01",
  "tour": "WTA",
  "surface": "Hard",
  "round": "R16",
  "best_of": 3,
  "score": "4-6 7-6 6-4",
  "outcome": "COMPLETED",
  "status": "COMPLETED",
  "duration_minutes": null,
  "winner_id": "wta_221434",
  "loser_id": "wta_260006",
  "winner_sets_won": 2,
  "loser_sets_won": 1,
  "scheduled_at": null,
  "tournament_name": "WTA 125K, Jingshan",
  "round_name": "Round of 16",
  "winner": {
    "id": "wta_221434",
    "name": "Aliona Falei",
    "ioc": "BLR",
    "seed": null,
    "entry": null,
    "rank": null,
    "is_winner": true
  },
  "loser": {
    "id": "wta_260006",
    "name": "Kristiana Sidorova",
    "ioc": "RUS",
    "seed": null,
    "entry": null,
    "rank": null,
    "is_winner": false
  },
  "player1": {
    "id": "wta_221434",
    "name": "Aliona Falei",
    "ioc": "BLR",
    "seed": null,
    "entry": null,
    "rank": null,
    "is_winner": true
  },
  "player2": {
    "id": "wta_260006",
    "name": "Kristiana Sidorova",
    "ioc": "RUS",
    "seed": null,
    "entry": null,
    "rank": null,
    "is_winner": false
  },
  "winner_side": 1,
  "sets": [
    {
      "set_number": 1,
      "winner_games": 4,
      "loser_games": 6,
      "player1_games": 4,
      "player2_games": 6,
      "tiebreak": null
    },
    {
      "set_number": 2,
      "winner_games": 7,
      "loser_games": 6,
      "player1_games": 7,
      "player2_games": 6,
      "tiebreak": null
    }
  ],
  "stats": {
    "winner": {
      "aces": 1,
      "double_faults": 6,
      "serve_points": 108,
      "first_serves_in": 75,
      "first_serves_won": 47,
      "second_serves_won": 11,
      "first_serve_pct": 69.4,
      "first_serve_win_pct": null,
      "second_serve_win_pct": null,
      "service_games_played": null,
      "break_points_saved": 9,
      "break_points_faced": null,
      "break_points_converted": null,
      "break_point_opportunities": null,
      "total_points_won": null
    },
    "loser": {
      "aces": 7,
      "double_faults": 6,
      "serve_points": 113,
      "first_serves_in": 67,
      "first_serves_won": 38,
      "second_serves_won": 17,
      "first_serve_pct": 59.3,
      "first_serve_win_pct": null,
      "second_serve_win_pct": null,
      "service_games_played": null,
      "break_points_saved": 6,
      "break_points_faced": null,
      "break_points_converted": null,
      "break_point_opportunities": null,
      "total_points_won": null
    }
  },
  "name": "WTA 125K, Jingshan",
  "starts_at": "2026-10-01T00:00:00+00:00"
}

GET/tennis/matches/{match_id}/stats

Match Statistics Slice

Serving/return statistics for one match (subset of the full match detail).

Parameter	In	Type	Description
match_id*	path	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/s365_2026_4866705/stats"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "match_id": "s365_2026_4866705",
  "stats": {
    "winner": {
      "aces": 1,
      "double_faults": 6,
      "serve_points": 108,
      "first_serves_in": 75,
      "first_serves_won": 47,
      "first_serve_pct": 69.4,
      "first_serve_won_pct": 62.7,
      "second_serve_won_pct": 40.7,
      "break_points_saved_pct": null,
      "second_serves_won": 11,
      "break_points_saved": 9,
      "break_points_faced": null
    },
    "loser": {
      "aces": 7,
      "double_faults": 6,
      "serve_points": 113,
      "first_serves_in": 67,
      "first_serves_won": 38,
      "first_serve_pct": 59.3,
      "first_serve_won_pct": 56.7,
      "second_serve_won_pct": 42.5,
      "break_points_saved_pct": null,
      "second_serves_won": 17,
      "break_points_saved": 6,
      "break_points_faced": null
    }
  },
  "sets": [
    {
      "set_number": 1,
      "winner_games": 4,
      "loser_games": 6,
      "player1_games": 4,
      "player2_games": 6,
      "tiebreak": null
    },
    {
      "set_number": 2,
      "winner_games": 7,
      "loser_games": 6,
      "player1_games": 7,
      "player2_games": 6,
      "tiebreak": null
    }
  ],
  "score": "4-6 7-6 6-4",
  "id": "s365_2026_4866705"
}

GET/tennis/matches/{match_id}/status

Unified Match Status

Normalizes scheduled/live/final and exceptional match states into one small payload.

Parameter	In	Type	Description
match_id*	path	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/s365_2026_4866705/status"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "match_id": "s365_2026_4866705",
  "status": "completed",
  "source_status": "COMPLETED",
  "scheduled_at": "2026-10-01T00:00:00+00:00",
  "last_updated_at": "2026-10-01T10:50:52.734115+00:00",
  "is_final": true,
  "id": "s365_2026_4866705",
  "starts_at": "2026-10-01T00:00:00+00:00"
}

GET/tennis/matches/{match_id}/timeline

Completed Match Timeline

Returns persisted set events; point-level history is retained for live-feed matches only.

Parameter	In	Type	Description
match_id*	path	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/s365_2026_4866705/timeline"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "match_id": "s365_2026_4866705",
  "status": "COMPLETED",
  "granularity": "set",
  "events": [
    {
      "event_type": "set_complete",
      "set_number": 1,
      "winner_games": 4,
      "loser_games": 6,
      "tiebreak": null
    },
    {
      "event_type": "set_complete",
      "set_number": 2,
      "winner_games": 7,
      "loser_games": 6,
      "tiebreak": null
    }
  ],
  "last_updated_at": "2026-10-01T10:50:52.734115+00:00",
  "coverage": {
    "point_history": false,
    "note": "Historical point-by-point data is not yet licensed or persisted."
  },
  "id": "s365_2026_4866705"
}

GET/tennis/matches/{match_id}/tournament-link

Resolve a Match Id to Its Tournament (Any Id Dialect)

Accepts any match id dialect (bare live s365_<gid>, archived s365_<year>_<gid>, or atp_<year>_<code>_<num>) and reports what tournament it belongs to. `tournament_id` is only ever a verified FK from the match archive; a live/upcoming match that has not been reconciled to a tournament row yet reports `tournament_id: null` with `tournament_name` (free text) and a `reason`, rather than a guessed id.

Parameter	In	Type	Description
match_id*	path	string

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/matches/s365_2026_4866705/tournament-link"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "match_id": "s365_2026_4866705",
  "input_id": "s365_2026_4866705",
  "source": "archive",
  "linked": true,
  "tournament_id": "s365_wta_2026_live-wta-125k-jingshan",
  "tournament_name": "WTA 125K, Jingshan",
  "reason": null,
  "id": "s365_2026_4866705",
  "name": "WTA 125K, Jingshan"
}

GET/tennis/schedule

Daily Tennis Schedule

Parameter	In	Type	Description
date*	query	string	Calendar date in the requested timezone
timezone	query	string	IANA timezone, e.g. America/New_Yorkdefault UTC
tour	query	string
limit	query	integer	Max scheduled matches to returnmin 1 · max 500
page_size	query	integer	Alias for limitmin 1 · max 500

bash

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.citoapi.com/api/v1/tennis/schedule?date=2026-10-01&page_size=2"

Real response (HTTP 200), captured from the production API; long arrays cut to two items.

json

{
  "success": true,
  "date": "2026-10-01",
  "timezone": "UTC",
  "items": [
    {
      "match_id": "fs_dQud0faE",
      "status": "COMPLETED",
      "source_status": "COMPLETED",
      "scheduled_at": "2026-10-01T00:00:00+00:00",
      "scheduled_at_local": null,
      "start_time_known": false,
      "last_updated_at": "2026-10-01T18:18:29.661162+00:00",
      "tour": "ATP",
      "tournament_id": "fs_atp_2026_m15-ann-arbor-mi",
      "tournament_name": "M15 Ann Arbor, MI",
      "round": "R16",
      "round_name": "Round of 16",
      "surface": "Hard",
      "player1": {
        "id": "atp_211609",
        "name": "Max Dahlin",
        "ioc": "SWE"
      },
      "player2": {
        "id": "atp_209060",
        "name": "Alexander Bernard",
        "ioc": "USA"
      },
      "winner_id": "atp_211609",
      "score": "7-5 7-6(3)",
      "id": "fs_dQud0faE",
      "name": "M15 Ann Arbor, MI",
      "starts_at": "2026-10-01T00:00:00+00:00"
    },
    {
      "match_id": "fs_n7Q5Dft1",
      "status": "COMPLETED",
      "source_status": "COMPLETED",
      "scheduled_at": "2026-10-01T00:00:00+00:00",
      "scheduled_at_local": null,
      "start_time_known": false,
      "last_updated_at": "2026-10-01T20:17:31.664971+00:00",
      "tour": "ATP",
      "tournament_id": "fs_atp_2026_m15-ann-arbor-mi",
      "tournament_name": "M15 Ann Arbor, MI",
      "round": "R16",
      "round_name": "Round of 16",
      "surface": "Hard",
      "player1": {
        "id": "atp_212149",
        "name": "Nikola Djosic",
        "ioc": "SUI"
      },
      "player2": {
        "id": "atp_213051",
        "name": "Thanaphat Boosarawongse",
        "ioc": "THA"
      },
      "winner_id": "atp_212149",
      "score": "7-6(6) 6-3",
      "id": "fs_n7Q5Dft1",
      "name": "M15 Ann Arbor, MI",
      "starts_at": "2026-10-01T00:00:00+00:00"
    }
  ],
  "total": 253,
  "page": 1,
  "page_size": 2,
  "total_pages": 127,
  "has_next": true,
  "has_prev": false,
  "starts_at": "2026-10-01T00:00:00+00:00"
}