DocsHead-to-head endpoints

Every meeting between two players, split every way.

One call returns the full rivalry: who leads, on which surface, at which level, in best-of-three and best-of-five, in tiebreaks and deciding sets, and the list of every match they played.

Get a free API keyRead the docs
  • Surface and level splits
  • Tiebreaks and deciding sets
  • Grids for a whole group
GET /tennis/h2h?player1_id=atp_104925&player2_id=atp_104745200 OK
$ curl "https://api.citoapi.com/api/v1/tennis/h2h?player1_id=atp_104925&player2_id=atp_104745" \ -H "x-api-key: $CITO_API_KEY"
{  "player1": {    "name": "Novak Djokovic",    "wins": 31  },  "player2": {    "name": "Rafael Nadal",    "wins": 29  },  "summary": {    "total_matches": 60,    "finals_matches": 29,    "grand_slam_matches": 18  },  "surface_breakdown": {    "hard": {      "player1_wins": 20,      "player2_wins": 7    },    "clay": {      "player1_wins": 9,      "player2_wins": 20    },    "grass": {      "player1_wins": 2,      "player2_wins": 2    }  },  "deciding_sets": {    "player1_deciding_set_wins": 5,    "player2_deciding_set_wins": 8  }}

Seamless Integration with our MCP Server

Give Claude, Cursor, and ChatGPT the tennis archive. One command writes the MCP config, agents call match, ranking and head-to-head tools with real player IDs instead of guessing, and your key stays on your machine.

MCPInstall the Cito MCP server
Claude
Cursor
OpenAI
Python
Cito API
Next.js
Discord
Slack
GitHub

A rivalry in one response

Head-to-head is more than a win count. These are the splits fans and models actually use.

Overall and finals

Total wins, the lead, and the record in finals.

By surface

Hard, clay, grass and carpet records side by side.

By level

Grand Slams, Masters 1000, Tour Finals, 500/250 and team events.

By format

Best-of-three and best-of-five records.

Tiebreaks and deciders

Tiebreaks won and deciding sets won by each player.

Head-to-head grids

A matrix of records for a whole group, such as the top 10, in one call.

What does the tennis head-to-head endpoint return?

Both players with their current and career-high ranking, a summary (total matches, finals, Grand Slam meetings), breakdowns by surface, level and best-of format, tiebreak and deciding-set records, and every match they played with the date, tournament, surface, round, winner and score.

Read from GET /api/v1/tennis/h2h?player1_id=atp_104925&player2_id=atp_104745 on 2026-10-24.
Djokovic vs NadalDjokovicNadalMatches
Overall312960
Hard20727
Clay92029
Grass224
Grand Slams71118
Masters 1000161329
Best of five71219
Deciding sets5813

Can I get head-to-head records for several players at once?

Yes. /tennis/h2h/matrix?player_ids=... returns a grid of records for every pair in the list, which is how a tournament preview or a rivalry table is built in one request instead of dozens.

GET /api/v1/tennis/h2h/matrix?player_ids=atp_207989,atp_206173,atp_100644
{
  "players": [
    { "id": "atp_207989", "name": "Carlos Alcaraz", "wins": 18 },
    { "id": "atp_206173", "name": "Jannik Sinner", "wins": 18 },
    { "id": "atp_100644", "name": "Alexander Zverev", "wins": 10 }
  ],
  "matrix": {
    "atp_207989": { "atp_206173": "11-7", "atp_100644": "7-6" },
    "atp_206173": { "atp_207989": "7-11", "atp_100644": "11-4" }
  }
}

How do I find the player IDs?

Search by name with /tennis/players/search?q=nadal, then pass the id values. IDs are stable across every match, ranking and stat row, so you can store them.

Endpoints you can ship with

Start on head-to-head: the two-player record, the path form, and the matrix.

Head-to-head

The full record between two players, split by surface and level, or a grid of records across a group of players.

View docs
  • GET/api/v1/tennis/h2h?player1_id=&player2_id=

    Wins, losses and every meeting between two players.

  • GET/api/v1/tennis/h2h/{player1_id}/{player2_id}

    The same record in path form.

  • GET/api/v1/tennis/h2h/matrix?player_ids=

    A head-to-head grid for several players at once.

Figures on this page were checked against the live API on 2026-10-24.

FAQs

Records, splits and player IDs

Can't find what you're looking for? Contact our customer support team

More tennis data

Pages that pair with head-to-head.

See plans

Add head-to-head to match previews

Call it on a free key now; the record, the splits and every meeting come back in one response.

Get a free API key