Skip to content

get_head_to_head

5 creditsStats + aggregationPOST /v1/get_head_to_head

Two players' finishes and rounds in every tournament they both played

Use it when you are comparing two players: who finished ahead in the tournaments they both played, and round by round.

Parameters

player_astringrequired
First player id.
player_bstringrequired
Second player id.
seasonstring | numberoptional
Season year, e.g. 2025.
leagueenum: golf | lpga | liv | dpwt | kornferryoptional
League. Defaults to golf. One of: golf, lpga, liv, dpwt, kornferry.

Notes

  • Over MCP, ask for it in plain English and the client calls get_head_to_head itself. Point any MCP client at https://mcp.birdieapi.com/mcp?key=YOUR_API_KEY.
  • Each call costs 5 credits, taken before it runs and refunded if the server errors.
  • Not the call you need? Find the right call by what you are trying to answer.

Request

curl -X POST https://mcp.birdieapi.com/v1/get_head_to_head \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "player_a": "9478",
  "player_b": "3470",
  "season": 2025
}'

Response

json
{
  "player_a": {
    "player_id": "9478",
    "name": "Scottie Scheffler"
  },
  "player_b": {
    "player_id": "3470",
    "name": "Rory McIlroy"
  },
  "summary": {
    "tournaments": 13,
    "a_ahead": 8,
    "b_ahead": 4,
    "tied": 1,
    "no_decision": 0,
    "rounds": 52,
    "a_better_rounds": 31,
    "b_better_rounds": 18,
    "even_rounds": 3,
    "a_minus_b_strokes_per_round": -0.65
  },
  "meetings": [
    {
      "tournament_id": "401703531",
      "name": "TOUR Championship",
      "season": 2025,
      "start_date": "2025-08-21",
      "major": false,
      "a_position": "T4",
      "a_status": "finished",
      "a_to_par": -14,
      "b_position": "T23",
      "b_status": "finished",
      "b_to_par": -6,
      "rounds": [
        {
          "round": 1,
          "a": 63,
          "b": 66
        },
        {
          "round": 2,
          "a": 69,
          "b": 67
        },
        {
          "round": 3,
          "a": 66,
          "b": 71
        }
      ],
      "finished_ahead": "9478"
    },
    {
      "tournament_id": "401703530",
      "name": "BMW Championship",
      "season": 2025,
      "start_date": "2025-08-14",
      "major": false,
      "a_position": "1",
      "a_status": "finished",
      "a_to_par": -15,
      "b_position": "T12",
      "b_status": "finished",
      "b_to_par": -3,
      "rounds": [
        {
          "round": 1,
          "a": 66,
          "b": 70
        },
        {
          "round": 2,
          "a": 65,
          "b": 66
        },
        {
          "round": 3,
          "a": 67,
          "b": 71
        }
      ],
      "finished_ahead": "9478"
    },
    {
      "tournament_id": "401703521",
      "name": "The Open",
      "season": 2025,
      "start_date": "2025-07-17",
      "major": true,
      "a_position": "1",
      "a_status": "finished",
      "a_to_par": -17,
      "b_position": "T7",
      "b_status": "finished",
      "b_to_par": -10,
      "rounds": [
        {
          "round": 1,
          "a": 68,
          "b": 70
        },
        {
          "round": 2,
          "a": 64,
          "b": 69
        },
        {
          "round": 3,
          "a": 67,
          "b": 66
        }
      ],
      "finished_ahead": "9478"
    }
  ],
  "count": 13
}

Response fields

player_aobject
player_a.player_idstring
player_a.namestring
player_bobject
player_b.player_idstring
player_b.namestring
summaryobject
summary.tournamentsnumber
summary.a_aheadnumber
summary.b_aheadnumber
summary.tiednumber
summary.no_decisionnumber
summary.roundsnumber
summary.a_better_roundsnumber
summary.b_better_roundsnumber
summary.even_roundsnumber
summary.a_minus_b_strokes_per_roundnumber
meetings[]array
List of objects
meetings[].tournament_idstring
meetings[].namestring
meetings[].seasonnumber
meetings[].start_datestring
meetings[].majorboolean
meetings[].a_positionstring
meetings[].a_statusstring
meetings[].a_to_parnumber
meetings[].b_positionstring
meetings[].b_statusstring
meetings[].b_to_parnumber
meetings[].rounds[]array
List of objects
meetings[].rounds[].roundnumber
meetings[].rounds[].anumber
meetings[].rounds[].bnumber
meetings[].finished_aheadstring
countnumber

Used in

  • Golf leaderboard and results data: Full PGA Tour leaderboards since 2001, every player in every field, with rounds, status and money; the LPGA, LIV and DP World Tour through the same tools.

Related endpoints

Try it

500 free credits every month: 100 calls to get_head_to_head, and no card.