Head-to-head tables

NBA-only. One player's offensive head-to-head table per season (leagueseasonmatchups): rows has one entry per defender he faced, the provider columns (GP, MATCHUP_MIN, PARTIAL_POSS, PLAYER_PTS, MATCHUP_FGM …) and defPlayerId. Filter by player (his offence) or defender (every table that lists that defender — his defence). Fetched for the season's most-used players, this season and the two before, by statsapi:season-matchups.

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

GEThttps://api.sportquanta.com/v1/nba/player-matchupsTry it

GETList NBA head-to-head tables for a season

GEThttps://api.sportquanta.comhttps://api-stage.sportquanta.comhttp://localhost:8082/v1/nba/player-matchups

Send

List NBA head-to-head tables for a season

Expand optional fieldsCollapse optional fields

NBA-only. One player's offensive head-to-head table per season (leagueseasonmatchups): rows has one entry per defender he faced, the provider columns (GP, MATCHUP_MIN, PARTIAL_POSS, PLAYER_PTS, MATCHUP_FGM …) and defPlayerId. Filter by player (his offence) or defender (every table that lists that defender — his defence). Fetched for the season's most-used players, this season and the two before, by statsapi:season-matchups.

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

Authorization

Authorizationstringheaderrequired

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

Bearer

Query

seasonintegerrequired

Season start year (2025 for the 2025-26 season).

playerstring

Canonical player id (offence).

defenderstring

Canonical player id found among a table's defenders.

limitinteger

List NBA head-to-head tables for a seasoncURL

200Example

Reference context: NBA.

Overview · Response conventions

List NBA head-to-head tables for a season

curl --request GET \
  --url 'https://api.sportquanta.com/v1/nba/player-matchups?season=1946' \
  --header 'Authorization: Bearer <token>'

200 · Example

{
  "data": {
    "season": 0,
    "items": [
      {}
    ]
  },
  "_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

seasonintegerrequired

Season start year (2025 for the 2025-26 season).

Required range: 1946 <= x, x <= 2100

playerstring

Canonical player id (offence).

defenderstring

Canonical player id found among a table's defenders.

limitintegerdefault:200

Required range: 1 <= x, x <= 2000

provenancebooleandefault:false

Opt in to per-field provenance on supported single game, match, team, player, and venue reads. Lists and composites accept the flag but generally omit provenance. It is returned under _meta.provenance only when source metadata exists.

Response

200400401403429500502503application/json

Every stored row for the season that matches the filters.

dataobjectrequired

data.seasonintegerrequired

data.itemsobject[]required

_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.