Skip to content

list_games

2 creditsBasic lookupPOST /v1/list_games

Data refreshed · changelog

Games with scores by season, date, range or team

Use it when you want scores for a date, a date range, a team or a season, newest first, with game ids for the detail endpoints.

Parameters

seasonnumber | stringoptional
Season by the year it ends: 2025 = 2024-25.
season_typeenum: regular | postseason | play_in | preseasonoptional
regular, postseason, play_in or preseason.
teamstringoptional
Team id or abbreviation.
datestringoptional
One date, YYYY-MM-DD (US Eastern).
fromstringoptional
From date, YYYY-MM-DD.
tostringoptional
To date, YYYY-MM-DD.
statusenum: scheduled | finaloptional
limitintegeroptional
Max games (default 50).
offsetintegeroptional
Page offset; use next_offset.
leagueenum: nba | wnba | ncaam | ncaaw | nbloptional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw, nbl.

Notes

  • Over MCP, ask for it in plain English and the client calls list_games itself. Point any MCP client at https://mcp.dunkapi.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.dunkapi.com/v1/list_games \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "team": "BOS",
  "season": 2026,
  "limit": 3
}'

Response

json
{
  "games": [
    {
      "game_id": "401869412",
      "season": 2026,
      "season_type": "postseason",
      "date": "2026-05-02",
      "starts_at": "2026-05-02T23:30:00.000Z",
      "status": "final",
      "home": {
        "team_id": "2",
        "abbrev": "BOS",
        "name": "Boston Celtics",
        "score": 100
      },
      "away": {
        "team_id": "20",
        "abbrev": "PHI",
        "name": "Philadelphia 76ers",
        "score": 109
      },
      "periods": 4,
      "overtime_periods": 0,
      "neutral_site": false,
      "conference_game": true,
      "venue": "TD Garden",
      "city": "Boston",
      "attendance": 19156
    },
    {
      "game_id": "401869410",
      "season": 2026,
      "season_type": "postseason",
      "date": "2026-04-30",
      "starts_at": "2026-05-01T00:00:00.000Z",
      "status": "final",
      "home": {
        "team_id": "20",
        "abbrev": "PHI",
        "name": "Philadelphia 76ers",
        "score": 106
      },
      "away": {
        "team_id": "2",
        "abbrev": "BOS",
        "name": "Boston Celtics",
        "score": 93
      },
      "periods": 4,
      "overtime_periods": 0,
      "neutral_site": false,
      "conference_game": true,
      "venue": "Xfinity Mobile Arena",
      "city": "Philadelphia",
      "attendance": 19746
    },
    {
      "game_id": "401869408",
      "season": 2026,
      "season_type": "postseason",
      "date": "2026-04-28",
      "starts_at": "2026-04-28T23:00:00.000Z",
      "status": "final",
      "home": {
        "team_id": "2",
        "abbrev": "BOS",
        "name": "Boston Celtics",
        "score": 97
      },
      "away": {
        "team_id": "20",
        "abbrev": "PHI",
        "name": "Philadelphia 76ers",
        "score": 113
      },
      "periods": 4,
      "overtime_periods": 0,
      "neutral_site": false,
      "conference_game": true,
      "venue": "TD Garden",
      "city": "Boston",
      "attendance": 19156
    }
  ],
  "count": 3,
  "next_offset": 3
}

Response fields

games[]array
List of objects
games[].game_idstring
games[].seasonnumber
games[].season_typestring
games[].datestring
games[].starts_atstring
games[].statusstring
games[].homeobject
games[].home.team_idstring
games[].home.abbrevstring
games[].home.namestring
games[].home.scorenumber
games[].awayobject
games[].away.team_idstring
games[].away.abbrevstring
games[].away.namestring
games[].away.scorenumber
games[].periodsnumber
games[].overtime_periodsnumber
games[].neutral_siteboolean
games[].conference_gameboolean
games[].venuestring
games[].citystring
games[].attendancenumber
countnumber
next_offsetnumber

Used in

Related endpoints

Try it

500 free credits every month: 250 calls to list_games, and no card.