Teams, Players & Rosters

The Cup calendar

NBA-only. The season's NBA Cup calendar from cup_calendars, written daily by the espn:cup-calendar adapter from the note ESPN's scoreboard puts on every cup game ("NBA Cup - Group Play", "NBA Cup - Quarterfinals", "NBA Cup - Semifinals", "NBA Cup Championship"), read for every day from October 15 to December 31 of the season's start year.

stages lists the four rounds in order (group, quarterfinal, semifinal, final). Each carries the ESPN scoreboard query dates with a game of the round — the US game day, ascending and unique — the number of games on them, and how many of those games still have TBD teams (placeholders); a round ESPN lists no game for yet has empty dates and games: 0. The games themselves carry the same round as cup_stage (and the group as cup_group) on /v1/nba/games.

Requires the stats entitlement (a paid plan). See Responses & Errors for the success envelope and availability rules.

GEThttps://api.sportquanta.com/v1/nba/cup-calendar

Reference context: NBA.

Overview · Response conventions

curl --request GET \
  --url 'https://api.sportquanta.com/v1/nba/cup-calendar?season=2026-27' \
  --header 'Authorization: Bearer <token>'

{
  "data": {
    "season": "<string>",
    "source": "<string>",
    "fetched_at": "<string>",
    "stages": [
      {
        "stage": "group",
        "dates": [
          "<string>"
        ],
        "games": 0,
        "placeholders": 0
      }
    ]
  },
  "_meta": {
    "request_id": "REQUEST_ID",
    "served_from": "live",
    "cache_ttl_seconds": 300
  }
}

Authorizations

Authorizationstringheaderrequired

Send a workspace API token in the Authorization: Bearer <token> header.

Query Parameters

seasonstringrequired

Required NBA season label (2026-27); a bare start year (2026) or 2026-2027 is read as the same season. Anything else is a 422.

Response

application/json

The season's NBA Cup calendar.

dataobjectrequired

A season's NBA Cup calendar (cup_calendars, written by the espn:cup-calendar adapter from ESPN's scoreboard notes) — the four rounds in order with their game days, game counts and TBD games.

data.seasonstringrequired

NBA season label, e.g. 2026-27.

data.sourcestringrequired

Always espn.

data.fetched_atstringrequired

When the adapter read ESPN's scoreboards (ISO-8601).

data.stagesobject[]required

group, quarterfinal, semifinal, final in that order.

data.stages.stageenum<string>required

Available options: group, quarterfinal, semifinal, final

data.stages.datesstring[]required

ESPN scoreboard query dates (YYYY-MM-DD, the US game day) with a game of the round, ascending and unique; empty until ESPN lists one.

data.stages.gamesintegerrequired

Games of the round on those dates, TBD ones included.

data.stages.placeholdersintegerrequired

Games of the round whose teams are not known yet (ESPN lists them as TBD @ TBD).

_metaobject

Response request/cache metadata. Optional evidence fields are specific to this handler; cache TTL does not measure source-data freshness.

_meta.request_idstring

_meta.served_fromenum<string>

Available options: live, cache

_meta.cache_ttl_secondsinteger

Response cache TTL; independent of source freshness. Omitted when zero.