> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.sandbox.blitzboardstats.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get schedule player statistics

> All player stat rows for one schedule (no pagination). Each category key is an array. Rows include teamId and teamName. Optional teamId query limits to one side. Omit categories to fetch all five; unrequested keys are `[]`.

## Scope

Stats are limited to the **single schedule** in the path. There is no season / multi-game aggregation and **no pagination** — each requested category returns its full list.

When both sides have recorded plays (home `teamOneId` and a linked `teamTwoId`), rows from **both teams** are included. Each row has `teamId` and `teamName` so you can tell which side the player belongs to.

The schedule’s home team (`teamOneId`) must belong to the API key organization.

## Response shape

```json theme={null}
{
  "data": {
    "quarterbackStat": [
      {
        "_id": "66f0a1b2c3d4e5f678901401",
        "teamId": "6917707a0e8f6ee5171235c2",
        "teamName": "valencia onee",
        "playerName": "Alex Johnson",
        "jerseyNumber": "10",
        "passAttempts": 120,
        "passCompletions": 80,
        "passYards": 980
      },
      {
        "_id": "66f0a1b2c3d4e5f678901402",
        "teamId": "6a9f05fa02936ccb365dc5de",
        "teamName": "test summary",
        "playerName": "Jordan Lee",
        "jerseyNumber": "7",
        "passAttempts": 45,
        "passCompletions": 28,
        "passYards": 310
      }
    ],
    "offensiveStat": [
      {
        "_id": "66f0a1b2c3d4e5f678901403",
        "teamId": "6917707a0e8f6ee5171235c2",
        "teamName": "valencia onee",
        "playerName": "Sam Rivera",
        "jerseyNumber": "21",
        "rushAttempts": 64,
        "rushYards": 412
      }
    ],
    "defensiveStat": [],
    "puntStat": [],
    "returnStat": []
  }
}
```

| Key               | Meaning                  |
| ----------------- | ------------------------ |
| `quarterbackStat` | Quarterback rows (array) |
| `offensiveStat`   | Offensive rows (array)   |
| `defensiveStat`   | Defensive rows (array)   |
| `puntStat`        | Punter rows (array)      |
| `returnStat`      | Punt-return rows (array) |

On each row:

| Field      | Meaning                                           |
| ---------- | ------------------------------------------------- |
| `teamId`   | Team this player row belongs to for this schedule |
| `teamName` | Display name for that team                        |

Unrequested categories (via `categories` filter) are **`[]`**.

## Optional `teamId` filter

Limit rows to one side of the game:

```http theme={null}
GET /v1/blitz-api/schedules/{scheduleId}/player-statistics?teamId=6917707a0e8f6ee5171235c2
```

* Omit `teamId` → both teams (when both have plays)
* Provide home `teamOneId` or linked away `teamTwoId` → that team only
* A `teamId` that is **not** on this schedule → `400` (`teamId must be teamOneId or teamTwoId on this schedule`)

Guest opponents with only `teamTwoName` (no `teamTwoId`) do not get a separate away bucket.

## Categories query

```http theme={null}
GET /v1/blitz-api/schedules/{scheduleId}/player-statistics?categories=quarterbackStat&categories=returnStat
```

Allowed values: `quarterbackStat`, `offensiveStat`, `defensiveStat`, `puntStat`, `returnStat`.

Optional: `searchTerm` (player display name or jersey number).


## OpenAPI

````yaml openapi.json GET /v1/blitz-api/schedules/{scheduleId}/player-statistics
openapi: 3.0.3
info:
  title: BlitzBoard Public API
  version: 1.0.0
  description: >-
    Organization-scoped public integration API for seasons, teams, players,
    schedules, and team player statistics.

    Authenticate with `Authorization: Bearer bb_live_...` (API key, not a login
    JWT).

    Generate keys from Organizations → organization detail at
    https://live.blitzboardstats.com/organizations.

    List seasons via GET /v1/blitz-api/seasons and pass `_id` as `season` when
    creating a team.
servers:
  - url: https://sandbox.blitzboardstats.com/api
    description: Sandbox
security:
  - ApiKeyBearer: []
tags:
  - name: Seasons
    description: List seasons to use when creating teams
  - name: Teams
    description: Team CRUD scoped to the API key organization
  - name: Players
    description: Players under a team
  - name: Schedules
    description: Schedule events under a team
paths:
  /v1/blitz-api/schedules/{scheduleId}/player-statistics:
    get:
      tags:
        - Schedules
      summary: Get schedule player statistics
      description: >-
        All player stat rows for **one schedule** (no pagination).


        When both sides have recorded plays (home and linked away), rows from
        **both teams** are included. Each row includes `teamId` and `teamName`.


        **Optional `teamId` query:** limit to one side (must be `teamOneId` or
        `teamTwoId` on this schedule). Omit to include both. Invalid `teamId` →
        `400`.


        **Response keys** (under `data`): each of `quarterbackStat`,
        `offensiveStat`, `defensiveStat`, `puntStat`, `returnStat` is an
        **array** of rows.


        **Categories filter:** omit `categories` to fetch all five. Unrequested
        keys are `[]`.


        Optional `searchTerm`. The schedule must belong to the API key
        organization.
      operationId: getSchedulePlayerStatistics
      parameters:
        - name: scheduleId
          in: path
          required: true
          schema:
            type: string
            example: 66f0a1b2c3d4e5f678901234
        - name: teamId
          in: query
          required: false
          description: >-
            Optional. Limit rows to one team on this schedule (home teamOneId or
            linked teamTwoId). Omit to include both teams when both have plays.
          schema:
            type: string
            example: 6917707a0e8f6ee5171235c2
        - name: categories
          in: query
          required: false
          description: Stat categories to include. Repeat for multiple values.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PublicPlayerStatisticsCategory'
          style: form
          explode: true
          example:
            - quarterbackStat
            - offensiveStat
        - name: searchTerm
          in: query
          required: false
          description: Filter by player display name or jersey number (partial match).
          schema:
            type: string
      responses:
        '200':
          description: Player statistics by category
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPlayerStatisticsResponse'
              examples:
                allCategories:
                  summary: All five categories (arrays)
                  value:
                    data:
                      quarterbackStat:
                        - teamId: 6917707a0e8f6ee5171235c2
                          teamName: valencia onee
                          _id: 66f0a1b2c3d4e5f678901401
                          playerName: Alex Johnson
                          jerseyNumber: '10'
                          passAttempts: 120
                          passCompletions: 80
                          passYards: 980
                        - teamId: 6a9f05fa02936ccb365dc5de
                          teamName: test summary
                          _id: 66f0a1b2c3d4e5f678901402
                          playerName: Jordan Lee
                          jerseyNumber: '7'
                          passAttempts: 45
                          passCompletions: 28
                          passYards: 310
                      offensiveStat:
                        - teamId: 6917707a0e8f6ee5171235c2
                          teamName: valencia onee
                          _id: 66f0a1b2c3d4e5f678901403
                          playerName: Sam Rivera
                          jerseyNumber: '21'
                          rushAttempts: 64
                          rushYards: 412
                        - teamId: 6a9f05fa02936ccb365dc5de
                          teamName: test summary
                          _id: 66f0a1b2c3d4e5f678901404
                          playerName: Casey Morgan
                          jerseyNumber: '88'
                          receptions: 22
                          receivingYards: 275
                      defensiveStat:
                        - teamId: 6917707a0e8f6ee5171235c2
                          teamName: valencia onee
                          _id: 66f0a1b2c3d4e5f678901405
                          playerName: Taylor Brooks
                          jerseyNumber: '44'
                          tackles: 38
                          interceptions: 2
                        - teamId: 6a9f05fa02936ccb365dc5de
                          teamName: test summary
                          _id: 66f0a1b2c3d4e5f678901406
                          playerName: Riley Quinn
                          jerseyNumber: '52'
                          tackles: 29
                          sacks: 4
                      puntStat:
                        - teamId: 6917707a0e8f6ee5171235c2
                          teamName: valencia onee
                          _id: 66f0a1b2c3d4e5f678901407
                          playerName: Pat Nguyen
                          jerseyNumber: '9'
                          punts: 18
                          puntYards: 720
                        - teamId: 6a9f05fa02936ccb365dc5de
                          teamName: test summary
                          _id: 66f0a1b2c3d4e5f678901408
                          playerName: Chris Alvarez
                          jerseyNumber: '3'
                          punts: 6
                          puntYards: 210
                      returnStat:
                        - teamId: 6917707a0e8f6ee5171235c2
                          teamName: valencia onee
                          _id: 66f0a1b2c3d4e5f678901409
                          playerName: Jamie Ortiz
                          jerseyNumber: '15'
                          puntReturns: 12
                          puntReturnYards: 148
                        - teamId: 6a9f05fa02936ccb365dc5de
                          teamName: test summary
                          _id: 66f0a1b2c3d4e5f678901410
                          playerName: Drew Patel
                          jerseyNumber: '25'
                          puntReturns: 8
                          puntReturnYards: 96
                partialCategories:
                  summary: categories=quarterbackStat only
                  value:
                    data:
                      quarterbackStat:
                        - teamId: 6917707a0e8f6ee5171235c2
                          teamName: valencia onee
                          _id: 66f0a1b2c3d4e5f678901401
                          playerName: Alex Johnson
                          jerseyNumber: '10'
                          passAttempts: 120
                          passCompletions: 80
                          passYards: 980
                      offensiveStat: []
                      defensiveStat: []
                      puntStat: []
                      returnStat: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    PublicPlayerStatisticsCategory:
      type: string
      enum:
        - quarterbackStat
        - offensiveStat
        - defensiveStat
        - puntStat
        - returnStat
      description: Player stat list category. Use as repeated `categories` query values.
    PublicPlayerStatisticsResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PublicPlayerStatisticsPayload'
      required:
        - data
    PublicPlayerStatisticsPayload:
      type: object
      description: >-
        Always includes all five keys as arrays. Unrequested categories are [].
        Each row includes teamId and teamName when attributable.
      required:
        - quarterbackStat
        - offensiveStat
        - defensiveStat
        - puntStat
        - returnStat
      properties:
        quarterbackStat:
          type: array
          items:
            type: object
            additionalProperties: true
        offensiveStat:
          type: array
          items:
            type: object
            additionalProperties: true
        defensiveStat:
          type: array
          items:
            type: object
            additionalProperties: true
        puntStat:
          type: array
          items:
            type: object
            additionalProperties: true
        returnStat:
          type: array
          items:
            type: object
            additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: number
        message:
          type: string
        timestamp:
          type: string
          format: date-time
        traceId:
          type: string
      example:
        error: 40101
        message: Invalid API key
        timestamp: '2026-09-13T14:45:41.317Z'
        traceId: req_41f0e6c8a5ea232a
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Outside API key organization scope or insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Public integration API key (`bb_live_...`). Not a login JWT.

````