get_matches

2 creditsBasic lookupPOST /v1/get_matches

Data refreshed Nov 12, 2026 · changelog

Results by competition, season, team, venue or date, with scores and margins

Use it when you want results: a competition's season, a team's matches, a ground's matches or a day's play.

Parameters

competitionstringoptional: Competition key from list_competitions (ipl, bbl, psl, blast, hundred, county, test, odi, t20i, ...).
seasonstringoptional: Season: a year (2024) or a split season (2024/25); a year also finds the split season that starts in it.
team_idstringoptional: Team id from list_teams.
opponent_idstringoptional: Only matches against this team too.
venuestringoptional: Part of the ground or city name.
datestringoptional: A day the match was played (YYYY-MM-DD); multi-day matches match on any day.
fromstringoptional: Start date on or after (YYYY-MM-DD).
tostringoptional: Start date on or before (YYYY-MM-DD).
formatenum: test | odi | t20 | first_class | list_aoptional
genderenum: male | femaleoptional
limitintegeroptional: Max matches (default 50).
offsetintegeroptional
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_matches itself. Point any MCP client at https://mcp.yorkerapi.com/mcp?key=YOUR_API_KEY.
Each call costs 2 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_matches \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "competition": "ipl",
  "season": "2025",
  "limit": 3
}'

Response

json

{
  "matches": [
    {
      "match_id": "1473511",
      "competition": "ipl",
      "event_name": "Indian Premier League",
      "season": "2025",
      "start_date": "2025-06-03",
      "end_date": "2025-06-03",
      "match_type": "T20",
      "format": "t20",
      "gender": "male",
      "event_stage": "Final",
      "event_match_number": null,
      "team1_id": "royal-challengers-bengaluru",
      "team1": "Royal Challengers Bengaluru",
      "team2_id": "punjab-kings",
      "team2": "Punjab Kings",
      "venue": "Narendra Modi Stadium, Ahmedabad",
      "city": "Ahmedabad",
      "toss_winner_id": "punjab-kings",
      "toss_decision": "field",
      "winner_id": "royal-challengers-bengaluru",
      "result": "win",
      "win_by_runs": 6,
      "win_by_wickets": null,
      "win_by_innings": null,
      "method": null,
      "team1_score": "190/9",
      "team2_score": "184/7"
    },
    {
      "match_id": "1473510",
      "competition": "ipl",
      "event_name": "Indian Premier League",
      "season": "2025",
      "start_date": "2025-06-01",
      "end_date": "2025-06-01",
      "match_type": "T20",
      "format": "t20",
      "gender": "male",
      "event_stage": "Qualifier 2",
      "event_match_number": null,
      "team1_id": "mumbai-indians",
      "team1": "Mumbai Indians",
      "team2_id": "punjab-kings",
      "team2": "Punjab Kings",
      "venue": "Narendra Modi Stadium, Ahmedabad",
      "city": "Ahmedabad",
      "toss_winner_id": "punjab-kings",
      "toss_decision": "field",
      "winner_id": "punjab-kings",
      "result": "win",
      "win_by_runs": null,
      "win_by_wickets": 5,
      "win_by_innings": null,
      "method": null,
      "team1_score": "203/6",
      "team2_score": "207/5"
    },
    {
      "match_id": "1473509",
      "competition": "ipl",
      "event_name": "Indian Premier League",
      "season": "2025",
      "start_date": "2025-05-30",
      "end_date": "2025-05-30",
      "match_type": "T20",
      "format": "t20",
      "gender": "male",
      "event_stage": "Eliminator",
      "event_match_number": null,
      "team1_id": "mumbai-indians",
      "team1": "Mumbai Indians",
      "team2_id": "gujarat-titans",
      "team2": "Gujarat Titans",
      "venue": "Maharaja Yadavindra Singh International Cricket Stadium, New Chandigarh",
      "city": "New Chandigarh",
      "toss_winner_id": "mumbai-indians",
      "toss_decision": "bat",
      "winner_id": "mumbai-indians",
      "result": "win",
      "win_by_runs": 20,
      "win_by_wickets": null,
      "win_by_innings": null,
      "method": null,
      "team1_score": "228/5",
      "team2_score": "208/6"
    }
  ],
  "count": 3,
  "next_offset": 3
}