get_matchup

5 creditsStats + aggregationPOST /v1/get_matchup

Data refreshed Nov 12, 2026 · changelog

A batter against a bowler: balls, runs, strike rate, dots and every dismissal

Use it when you want a batter against one bowler: balls, runs, strike rate, dots and every dismissal.

Parameters

batter_idstringrequired: Batter's player id.
bowler_idstringrequired: Bowler's player id.
formatenum: test | odi | t20 | first_class | list_aoptional
competitionstringoptional: Competition key from list_competitions (ipl, bbl, test, odi, t20i, ...).
leagueenum: cricket | test | odi | t20i | ipl | bbl | psl | cpl | blast | hundred | sa20 | ilt20 | county | wbbl | wpl | hundred_womenoptional: League. Defaults to cricket. One of: cricket, test, odi, t20i, ipl, bbl, psl, cpl, blast, hundred, sa20, ilt20, county, wbbl, wpl, hundred_women.

Notes

Over MCP, ask for it in plain English and the client calls get_matchup itself. Point any MCP client at https://mcp.yorkerapi.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.yorkerapi.com/v1/get_matchup \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "batter_id": "30a45b23",
  "bowler_id": "462411b3"
}'

Response

json

{
  "batter": {
    "player_id": "30a45b23",
    "name": "SPD Smith"
  },
  "bowler": {
    "player_id": "462411b3",
    "name": "JJ Bumrah"
  },
  "summary": {
    "matches": 33,
    "innings": 37,
    "runs": 281,
    "balls": 412,
    "outs": 10,
    "fours": 31,
    "sixes": 4,
    "dots": 259,
    "average": 28.1,
    "strike_rate": 68.2,
    "dismissals": 9,
    "balls_per_dismissal": 45.8
  },
  "by_format": [
    {
      "format": "test",
      "matches": 8,
      "innings": 12,
      "runs": 95,
      "balls": 227,
      "outs": 5,
      "fours": 9,
      "sixes": 1,
      "dots": 172,
      "average": 19,
      "strike_rate": 41.85
    },
    {
      "format": "odi",
      "matches": 14,
      "innings": 14,
      "runs": 103,
      "balls": 121,
      "outs": 2,
      "fours": 16,
      "sixes": 0,
      "dots": 67,
      "average": 51.5,
      "strike_rate": 85.12
    },
    {
      "format": "t20",
      "matches": 11,
      "innings": 11,
      "runs": 83,
      "balls": 64,
      "outs": 3,
      "fours": 6,
      "sixes": 3,
      "dots": 20,
      "average": 27.67,
      "strike_rate": 129.69
    }
  ],
  "dismissals": [
    {
      "match_id": "895815",
      "date": "2016-01-23",
      "competition": "odi",
      "innings": 1,
      "delivery": "11.5",
      "wicket_kind": "caught"
    },
    {
      "match_id": "980957",
      "date": "2016-05-01",
      "competition": "ipl",
      "innings": 1,
      "delivery": "9.2",
      "wicket_kind": "caught"
    },
    {
      "match_id": "1178402",
      "date": "2019-04-13",
      "competition": "ipl",
      "innings": 2,
      "delivery": "18.1",
      "wicket_kind": "caught"
    }
  ],
  "count": 412
}