---
title: "Head-to-head record between two ATP/WTA players (Build+)"
method: GET
path: "/v1/tennis/players/h2h"
tags: ["Tennis"]
---

# Head-to-head record between two ATP/WTA players (Build+)

`GET /v1/tennis/players/h2h`

## Request

- Base URL: `https://api.playcallerapp.com`
- URL: `https://api.playcallerapp.com/v1/tennis/players/h2h`
- Auth: API key in header `X-PlayCaller-Key`

Computes a head-to-head match record between two players from stored ESPN match results. Player names are case-insensitive partial matches.

**Tier access:** Build, Growth, Pro Insights, Syndicate Alpha

## Query parameters

- `player1` string, required
- `player2` string, required
- `tour` 'atp' | 'wta'
- `limit` integer

## Response `200`

Head-to-head record and match history

- object
  - `success` boolean
  - `endpoint` string
  - `players` object
    - `player1` string
    - `player2` string
  - `h2h_record` object: Win counts keyed by each player's search name, plus total_matches
  - `matches` object[]
    - `date` string
    - `tour` string
    - `tournament` string
    - `round` string
    - `player1` string
    - `player2` string
    - `score_p1` integer
    - `score_p2` integer
    - `winner` string, nullable
    - `is_final` boolean
  - `meta` ResponseMeta
    - `sport` string
    - `league` string: Present on multi-sport (ESPN-backed) endpoints; mirrors sport unless a sport has sub-leagues (e.g. soccer: epl/mls).
    - `tier` string
    - `calls_remaining_this_month` integer
    - `documentation_url` string, uri

## Other responses

- `400`: Missing player1 or player2 query parameter
- `401`: Missing or invalid API key
- `402`: Build tier or higher required
- `404`: No head-to-head matches found for the given players
- `429`: Rate limit or monthly quota exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/playcallerapp/apis/playcaller-data-api.md) · [All operations](https://skmtc.dev/playcallerapp/apis/playcaller-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/playcallerapp/apis/playcaller-data-api/revisions/100c0a3ffbfe?raw)