Season Stats & Analytics

Season starters & lineups

NPB-only path (MLB, KBO and NPB expose the same shape under their own prefix). Walks a season's games in canonical-id order and returns, per game, both starting pitchers (appearance_order 1: id, name, throwing hand, IP, pitches, runs, earned runs, decision), the starting catcher (sub_order 0, position C), the starting nine per side in batting order, plus scheduled start, venue and the line score. Built from the stored box scores only — no upstream call. A game with no box rows yet is listed with empty sides; counters a source does not publish (KBO pitch counts) are null, never 0.

Cursor pagination: pass next_cursor back as cursor. Optional team restricts to games where the canonical team id is home or away.

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

GEThttps://api.sportquanta.com/v1/npb/games/lineups

Reference context: NPB.

Overview · Response conventions

curl --request GET \
  --url 'https://api.sportquanta.com/v1/npb/games/lineups?season=1920' \
  --header 'Authorization: Bearer <token>'

{
  "data": {
    "season": 0,
    "team_id": "<string>",
    "items": [
      {
        "game_id": "<string>",
        "season": 0,
        "game_type": "<string>",
        "status": "<string>",
        "schedule_date": "<string>",
        "scheduled_start_utc": "<string>",
        "venue_id": "<string>",
        "home_team_id": "<string>",
        "away_team_id": "<string>",
        "linescore": {
          "home_runs": 0,
          "away_runs": 0,
          "inning": 0,
          "is_top_inning": true,
          "innings": [
            {
              "num": 0,
              "home_runs": 0,
              "away_runs": 0,
              "home_hits": 0,
              "away_hits": 0,
              "home_errors": 0,
              "away_errors": 0
            }
          ]
        },
        "home": {
          "team_id": "<string>",
          "starting_pitcher": {
            "player_id": "<string>",
            "name": "<string>",
            "hand": "<string>",
            "ip": 0,
            "pitches": 0,
            "runs": 0,
            "earned_runs": 0,
            "decision": "<string>"
          },
          "starting_catcher": {
            "player_id": "<string>",
            "name": "<string>",
            "batting_order": 0
          },
          "batters": [
            {
              "batting_order": 0,
              "player_id": "<string>",
              "name": "<string>",
              "position": "<string>",
              "bats": "<string>"
            }
          ],
          "starter_ids": [
            "<string>"
          ]
        },
        "away": {
          "team_id": "<string>",
          "starting_pitcher": {
            "player_id": "<string>",
            "name": "<string>",
            "hand": "<string>",
            "ip": 0,
            "pitches": 0,
            "runs": 0,
            "earned_runs": 0,
            "decision": "<string>"
          },
          "starting_catcher": {
            "player_id": "<string>",
            "name": "<string>",
            "batting_order": 0
          },
          "batters": [
            {
              "batting_order": 0,
              "player_id": "<string>",
              "name": "<string>",
              "position": "<string>",
              "bats": "<string>"
            }
          ],
          "starter_ids": [
            "<string>"
          ]
        }
      }
    ],
    "next_cursor": "<string>"
  },
  "_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

Required season year (1920–2100). Availability of historical data is separate from accepted query values.

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

teamstring

Canonical team id; restricts to that team's home and away games.

cursorstring

Opaque cursor from the previous page's next_cursor.

limitintegerdefault:50

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

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

application/json

One page of per-game starters.

dataobjectrequired

One cursor page of per-game starters assembled from stored box scores.

data.seasonintegerrequired

data.team_idstring

data.itemsobject[]required

data.items.game_idstringrequired

data.items.seasonintegerrequired

data.items.game_typestring

data.items.statusstring

data.items.schedule_datestring

data.items.scheduled_start_utcstring

data.items.venue_idstring

data.items.home_team_idstring

data.items.away_team_idstring

data.items.linescoreobject

data.items.linescore.home_runsinteger

data.items.linescore.away_runsinteger

data.items.linescore.inninginteger

data.items.linescore.is_top_inningboolean

data.items.linescore.inningsobject[]

data.items.linescore.innings.numinteger

data.items.linescore.innings.home_runsinteger

data.items.linescore.innings.away_runsinteger

data.items.linescore.innings.home_hitsinteger

data.items.linescore.innings.away_hitsinteger

data.items.linescore.innings.home_errorsinteger

data.items.linescore.innings.away_errorsinteger

data.items.homeobject | nullrequired

Null only when the game has no home team id yet.

data.items.home.team_idstringrequired

data.items.home.starting_pitcherobject | nullrequired

The appearance_order 1 pitcher; null until a box score exists.

data.items.home.starting_pitcher.player_idstringrequired

data.items.home.starting_pitcher.namestring

data.items.home.starting_pitcher.handstring | nullrequired

Throwing hand (L/R) from the players collection; null when unknown.

data.items.home.starting_pitcher.ipnumber | nullrequired

Innings pitched as a decimal (5.667 for 5.2).

data.items.home.starting_pitcher.pitchesinteger | nullrequired

Pitch count; null when the source does not publish it (KBO).

data.items.home.starting_pitcher.runsinteger | nullrequired

data.items.home.starting_pitcher.earned_runsinteger | nullrequired

data.items.home.starting_pitcher.decisionstring | nullrequired

W | L | S (NPB also H) or null.

data.items.home.starting_catcherobject | nullrequired

The sub_order 0 row at position C; null when no starter was listed at C.

data.items.home.starting_catcher.player_idstringrequired

data.items.home.starting_catcher.namestring

data.items.home.starting_catcher.batting_orderintegerrequired

data.items.home.battersobject[]required

The starting nine (sub_order 0, batting_order 1–9) in batting order; empty until a box score exists.

data.items.home.batters.batting_orderintegerrequired

data.items.home.batters.player_idstringrequired

data.items.home.batters.namestring

data.items.home.batters.positionstring | nullrequired

data.items.home.batters.batsstring | nullrequired

Batting side (L/R/S) from the players collection; null when unknown.

data.items.home.starter_idsstring[]required

data.items.awayobject | nullrequired

data.items.away.team_idstringrequired

data.items.away.starting_pitcherobject | nullrequired

The appearance_order 1 pitcher; null until a box score exists.

data.items.away.starting_pitcher.player_idstringrequired

data.items.away.starting_pitcher.namestring

data.items.away.starting_pitcher.handstring | nullrequired

Throwing hand (L/R) from the players collection; null when unknown.

data.items.away.starting_pitcher.ipnumber | nullrequired

Innings pitched as a decimal (5.667 for 5.2).

data.items.away.starting_pitcher.pitchesinteger | nullrequired

Pitch count; null when the source does not publish it (KBO).

data.items.away.starting_pitcher.runsinteger | nullrequired

data.items.away.starting_pitcher.earned_runsinteger | nullrequired

data.items.away.starting_pitcher.decisionstring | nullrequired

W | L | S (NPB also H) or null.

data.items.away.starting_catcherobject | nullrequired

The sub_order 0 row at position C; null when no starter was listed at C.

data.items.away.starting_catcher.player_idstringrequired

data.items.away.starting_catcher.namestring

data.items.away.starting_catcher.batting_orderintegerrequired

data.items.away.battersobject[]required

The starting nine (sub_order 0, batting_order 1–9) in batting order; empty until a box score exists.

data.items.away.batters.batting_orderintegerrequired

data.items.away.batters.player_idstringrequired

data.items.away.batters.namestring

data.items.away.batters.positionstring | nullrequired

data.items.away.batters.batsstring | nullrequired

Batting side (L/R/S) from the players collection; null when unknown.

data.items.away.starter_idsstring[]required

data.next_cursorstring | nullrequired

Pass back as cursor for the next page; null on the last page.

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