Major League Baseball Stats API

openapi: 3.0.1
info:
  title: API Documentation Analytics Stats API
  description: Official API for Major League Baseball.
  version: 2.0.0
servers:
- url: https://statsapi.mlb.com
  description: Production
- url: https://beta-statsapi.mlb.com
  description: Beta
- url: https://qa-statsapi.mlb.com
  description: QA
- url: http://localhost:8080
  description: Local
tags:
- name: Stats
  description: Operations pertaining to stats
paths:
  /api/v1/stats:
    get:
      tags:
      - Stats
      summary: View stats
      operationId: stats_2
      parameters:
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
      - name: personId
        in: query
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: false
        schema:
          type: integer
          format: int32
      - name: teamId
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          type: integer
          format: int32
      - name: teamIds
        in: query
        description: Comma delimited list of Unique Team identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: group
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: true
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
      - name: gameType
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          $ref: '#/components/schemas/GameTypeEnum'
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Sports
      - name: sportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
        x-lookup:
          name: Sports
      - name: leagueId
        in: query
        description: Unique League Identifier
        required: false
        schema:
          type: integer
          format: int32
      - name: leagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: leagueListId
        in: query
        description: Unique League List Identifier
        required: false
        schema:
          $ref: '#/components/schemas/LeagueListsEnum'
      - name: metrics
        in: query
        description: Name of metric(s) for metric log stats.  Available metrics in /api/v1/metrics
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/MetricType'
      - name: gamePk
        in: query
        description: Unique Primary Key Representing a Game
        required: false
        schema:
          type: integer
          format: int32
      - name: batterTeamId
        in: query
        description: A unique identifier for the batter's team
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: pitcherTeamId
        in: query
        description: A unique identifier for the pitcher's team
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: batterId
        in: query
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: false
        schema:
          type: integer
          format: int32
      - name: pitcherId
        in: query
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: false
        schema:
          type: integer
          format: int32
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: combineSits
        in: query
        description: 'If true, gathers stats where all of the situational criteria are met. If false, returns stats where any of the situational criteria are met. Default: false'
        required: false
        schema:
          type: boolean
      - name: opposingTeamId
        in: query
        description: A unique identifier for the opposing team. Must be used with Team ID
        required: false
        schema:
          type: integer
          format: int32
      - name: fields
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: sortStat
        in: query
        description: Baseball stat to sort splits by.
        required: false
        schema:
          $ref: '#/components/schemas/BaseballStatsEnum'
      - name: order
        in: query
        description: The order of sorting, ascending or descending
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: playerPool
        in: query
        description: Return "ALL" or only "QUALIFIED" players based on plate appearances.
        required: false
        schema:
          $ref: '#/components/schemas/PlayerPoolEnum'
      - name: position
        in: query
        description: 'Position number. Format: 1, 2, 3, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/BaseballPosition'
      - name: startDate
        in: query
        description: 'Start date for range of data (must be used with end date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: 'End date for range of data (must be used with start date). Format: MM/DD/YYYY'
        required: false
        schema:
          type: string
          format: date
      - name: daysBack
        in: query
        description: Returns results from the last 'X' days (Starting from yesterday).
        required: false
        schema:
          type: integer
          format: int32
      - name: gamesBack
        in: query
        description: Returns results from the last 'X' games played.
        required: false
        schema:
          type: integer
          format: int32
      - name: excludeTradedPlayers
        in: query
        description: Excludes players who have since been traded from the input team
        required: false
        schema:
          type: boolean
      - name: offset
        in: query
        description: The pointer to start for a return set; used for pagination
        required: false
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatsRestObject'
  /api/v1/stats/search:
    get:
      tags:
      - Stats
      summary: View stats from search
      operationId: beastStats
      parameters:
      - name: group
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
      - name: gamePks
        in: query
        description: Comma delimited list of unique primary keys
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: playIds
        in: query
        description: Comma delimited list of unique play identifiers
        required: false
        schema:
          type: array
          items:
            type: string
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - name: gameTypes
        in: query
        description: Type of Game. Available types in /api/v1/gameTypes
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GameTypeEnum'
      - name: date
        in: query
        description: 'Date of Game. Format: YYYY-MM-DD'
        required: false
        schema:
          type: string
          format: date
      - name: startDate
        in: query
        description: 'Date of Game. Format: YYYY-MM-DD'
        required: false
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: 'Date of Game. Format: YYYY-MM-DD'
        required: false
        schema:
          type: string
          format: date
      - name: teamIds
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: pitcherTeamIds
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: batterTeamIds
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: sportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
        x-lookup:
          name: Sports
      - name: pitcherSportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
        x-lookup:
          name: Sports
      - name: batterSportIds
        in: query
        description: Comma delimited list of top level organizations of a sport
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
        x-lookup:
          name: Sports
      - name: leagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: pitcherLeagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: batterLeagueIds
        in: query
        description: Comma delimited list of Unique league identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: divisionIds
        in: query
        description: Comma delimited list of Unique League Identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: pitcherDivisionIds
        in: query
        description: Comma delimited list of Unique League Identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: batterDivisionIds
        in: query
        description: Comma delimited list of Unique League Identifiers
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: pitchersOnTeamIds
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: battersOnTeamIds
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: playerIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: playerPool
        in: query
        description: Return "ALL" or only "QUALIFIED" players based on plate appearances.
        required: false
        schema:
          $ref: '#/components/schemas/PlayerPoolEnum'
      - name: pitcherIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: batterIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: catcherIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: firstBasemanIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: secondBasemanIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: thirdBasemanIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: shortstopIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: leftFielderIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: centerFielderIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: rightFielderIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: runnerFirstIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: runnerSecondIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: runnerThirdIds
        in: query
        description: A unique identifier for a player
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: venueIds
        in: query
        description: Unique Venue Identifier
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: pitchHand
        in: query
        description: Handedness of pitcher
        required: false
        schema:
          type: string
      - name: batSide
        in: query
        description: Bat side of hitter
        required: false
        schema:
          type: string
      - name: pitchTypes
        in: query
        description: Classification of pitch (fastball, curveball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/PitchType'
      - name: pitchCodes
        in: query
        description: Result of the pitch (ball, called strike, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/PitchCode'
      - name: eventTypes
        in: query
        description: Type of event
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/EventType'
      - name: positions
        in: query
        description: All of the details of a player's position
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/BaseballPosition'
      - name: primaryPositions
        in: query
        description: All of the details of a player's position
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/BaseballPosition'
      - name: minPitchSpeed
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxPitchSpeed
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minSpinRate
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxSpinRate
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minExtension
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxExtension
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minExitVelocityAgainst
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxExitVelocityAgainst
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minLaunchAngleAgainst
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxLaunchAngleAgainst
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minExitVelocity
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxExitVelocity
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minLaunchAngle
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxLaunchAngle
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minHomeRunDistance
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxHomeRunDistance
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minHitDistance
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxHitDistance
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minHangTime
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxHangTime
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minHitProbability
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxHitProbability
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: minCatchProbability
        in: query
        description: Minimum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: maxCatchProbability
        in: query
        description: Maximum value to filter on
        required: false
        schema:
          type: number
          format: double
      - name: isBarrel
        in: query
        description: Whether or not a play resulted in a barreled ball
        required: false
        schema:
          type: boolean
      - name: hitTrajectories
        in: query
        description: Trajectory of hit (line drive, fly ball, etc...)
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/HitTrajectory'
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The pointer to start for a return set; used for pagination
        required: false
        schema:
          type: integer
          format: int32
      - name: groupBy
        in: query
        description: Group stats by PLAYER, TEAM, SEASON, VENUE, SPORT or STAT_GROUP
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GroupByEnum'
      - name: compareOver
        in: query
        description: Group stats by PLAYER, TEAM, SEASON, VENUE, SPORT or STAT_GROUP
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/GroupByEnum'
      - name: sortStat
        in: query
        description: Baseball stat to sort splits by.
        required: false
        schema:
          $ref: '#/components/schemas/BaseballStatsEnum'
      - name: sortModifier
        in: query
        description: The prefix modifier for the sort stat.  avg, min, max. I.E minExitVelocity, maxLaunchAngle, avgHitDistance
        required: false
        schema:
          $ref: '#/components/schemas/AggregateSortTypeEnum'
      - name: sortOrder
        in: query
        description: The order of sorting, ascending or descending
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: percentile
        in: query
        description: Only return averages above this percentile. used for best effort plays
        required: false
        schema:
          type: integer
          format: int32
      - name: minOccurrences
        in: query
        description: Minimum occurrences to filter upon
        required: false
        schema:
          type: integer
          format: int32
      - name: minPlateAppearances
        in: query
        description: Minimum occurrences to filter upon
        required: false
        schema:
          type: integer
          format: int32
      - name: minInnings
        in: query
        description: Minimum occurrences to filter upon
        required: false
        schema:
          type: integer
          format: int32
      - name: qualifierRate
        in: query
        description: Minimum occurrences to filter upon
        required: false
        schema:
          type: number
          format: double
      - name: sitCodes
        in: query
        description: Situation code for a given stat split.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: showTotals
        in: query
        description: Columns to return totals
        required: false
        schema:
          type: boolean
      - name: includeNullMetrics
        in: query
        description: Show events with null metrics
        required: false
        schema:
          type: boolean
      - name: statFields
        in: query
        description: Baseball stat fields to populate
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatField'
      - name: atBatNumbers
        in: query
        description: 'The at bat number of a given game. Format: 1, 2, 3, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: pitchNumbers
        in: query
        description: 'The pitch number of a given game. Format: 1, 2, 3, etc'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
      - name: fields
        in: query
        description: 'Comma delimited list of specific fields to be returned. Format: topLevelNode, childNode, attribute'
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: debug
        in: query
        required: false
        schema:
          type: boolean
      - name: activeStatus
        in: query
        description: Whether or not a player is active
        required: false
        schema:
          $ref: '#/components/schemas/PlayerActiveStatusEnum'
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StatContainerRestObject'
  /api/v1/stats/metrics:
    get:
      tags:
      - Stats
      summary: View metric stats
      operationId: metricStats
      parameters:
      - name: personId
        in: query
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: false
        schema:
          type: integer
          format: int32
      - name: personIds
        in: query
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: false
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: batterId
        in: query
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: false
        schema:
          type: integer
          format: int32
      - name: pitcherId
        in: query
        description: 'Unique Player Identifier. Format: 434538, 429665, etc'
        required: false
        schema:
          type: integer
          format: int32
      - name: teamId
        in: query
        description: 'Unique Team Identifier. Format: 141, 147, etc'
        required: false
        schema:
          type: integer
          format: int32
      - name: stats
        in: query
        description: 'Type of statistics. Format: Individual, Team, Career, etc. Available types in /api/v1/statTypes'
        required: true
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatType'
      - name: group
        in: query
        description: Category of statistic to return. Available types in /api/v1/statGroups
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/StatGroup'
      - name: season
        in: query
        description: Season of play
        required: false
        schema:
          type: string
      - name: seasons
        in: query
        description: Comma delimited list of Seasons of play
        required: false
        schema:
          type: array
          items:
            type: string
      - name: sportId
        in: query
        description: Top level organization of a sport
        required: false
        schema:
          type: integer
          format: int32
        x-lookup:
          name: Sports
      - name: opposingTeamId
        in: query
        description: A unique identifier for the opposing team. Must be used with Team ID
        required: false
        schema:
          type: integer
          format: int32
      - name: opposingPlayerId
        in: query
        description: A unique identifier for the opposing team
        required: false
        schema:
          type: integer
          format: int32
      - name: position
        in: query
        description: All of the details of a player's position
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/BaseballPosition'
      - name: eventType
        in: query
        description: Type of event
        required: false
        schema:
          uniqueItems: true
          type: array
   

# --- truncated at 32 KB (287 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/major-league-baseball/refs/heads/main/openapi/major-league-baseball-stats-api-openapi.yml