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

# List sports games

> Find the game and team ids that sports monitors take as subjects

export const SportsExperimental = () => <Warning>
    <strong>The sports endpoints are experimental.</strong> They supply monitor subjects, and their shapes can change without a deprecation window.
  </Warning>;

<SportsExperimental />

## Notes

* To authenticate, you'll need a [Tako API key](https://tako.com/console/api-keys). It's best practice to store it as an environment variable to avoid hardcoding sensitive credentials in your code.
* This is the **subject lookup for sports monitors.** Find the game or team here, then pass its id to [Create a monitor](/api-reference/monitors-create).
* Games come back soonest first. `limit` defaults to 100 and maxes at 500; pass a response's `next_cursor` back as `cursor` for the next page.
* Filter with `league` (a league id such as `NBA` or `EPL`, case-insensitive) and `team` (a team id, matched on either side of the game).
* Rate limits are 60 requests a minute and 5,000 a day, per user.
* `home` and `away` are `null` for events without teams, such as F1 and NASCAR. `title` is the only label those rows carry.

## Which id goes where

| Field                | Monitor type that takes it                                      | As        |
| -------------------- | --------------------------------------------------------------- | --------- |
| `id`                 | Any sports monitor that watches a game                          | `game_id` |
| `home.id`, `away.id` | `sports.game_start`, `sports.game_result`, `sports.score_event` | `team_id` |

<Warning>
  **Only a `live_event` row's `id` works as a `game_id`.** A row whose `source` is `schedule_table` is an FBS or FCS football game that only the football schedule table records — its `id` belongs to that table, no live document exists for it, and no monitor accepts it. Only `live_event` rows can carry odds.
</Warning>

## The window

`from` and `to` are ISO 8601, and a naive value reads as UTC. They default to one day back and seven days ahead, which is the whole range the schedule covers — a window outside it is rejected with a `400`.

`status` defaults to `scheduled,live`, because a finished game can't be monitored. Pass `final` to include the games that finished inside the one-day tail.

## Reading `odds_available`

`odds_available` is `true` when the game document already holds a market. Prematch odds arrive inside a per-sport window, so a game further out reports `false` until that window opens. **A monitor create works either way** — a `false` here isn't a reason to wait.


## OpenAPI

````yaml GET /v1/sports/games
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
  - url: https://tako.com/api/
    description: Tako Production API Server
security: []
paths:
  /v1/sports/games:
    get:
      tags:
        - sports
      summary: List games
      description: >-
        Games from one day back to seven days ahead by default, soonest first.
        Each row's id is what a sports monitor takes as game_id, and its home.id
        and away.id are what sports.game_start, sports.game_result and
        sports.score_event take as team_id. odds_available says whether the game
        document already holds a market. Prematch odds arrive inside a per-sport
        window, so a game further out reports false until that window opens; a
        monitor create works either way.


        **Experimental.** The sports endpoints supply monitor subjects, and
        their shapes can change without a deprecation window.
      operationId: listSportsGames
      parameters:
        - description: A league id, such as NBA or EPL. Case-insensitive.
          required: false
          schema:
            type: string
          name: league
          in: query
        - description: A team id. Matches games where the team plays on either side.
          required: false
          schema:
            type: string
          name: team
          in: query
        - description: >-
            Window start, ISO 8601. Defaults to one day ago, which is the
            earliest the schedule covers. A naive value reads as UTC.
          required: false
          schema:
            type: string
            format: date-time
          name: from
          in: query
        - description: >-
            Window end, ISO 8601. Defaults to seven days ahead, which is the
            furthest the schedule covers. A window outside that range is
            rejected.
          required: false
          schema:
            type: string
            format: date-time
          name: to
          in: query
        - description: >-
            Keep only games in these states, comma-separated. Defaults to
            scheduled,live — a finished game can't be monitored. Pass final to
            include the games that finished inside the one-day lookback.
          required: false
          schema:
            type: string
            default: scheduled,live
            examples:
              - scheduled,live
              - final
          name: status
          in: query
        - description: Games per page. Defaults to 100, maximum 500.
          required: false
          schema:
            type: integer
            maximum: 500
            minimum: 1
            default: 100
          name: limit
          in: query
        - description: >-
            The next_cursor from the previous page. Opaque; pass it back
            unchanged.
          required: false
          schema:
            type: string
          name: cursor
          in: query
      responses:
        '200':
          description: Games in the window, soonest first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GamesResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '429':
          description: 'Rate limit exceeded: 60 requests a minute or 5000 a day, per user.'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    type: string
                type: object
                required:
                  - detail
      security:
        - apiKey: []
components:
  schemas:
    GamesResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GameResponse'
          type: array
          title: Items
        generated_at:
          type: string
          format: date-time
          title: Generated At
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Pass as 'cursor' to get the next page. Null on the last page.
      type: object
      required:
        - items
        - generated_at
      title: GamesResponse
      description: Games in the window, soonest first.
    BaseAPIError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
      type: object
      required:
        - error_message
        - error_type
      title: BaseAPIError
    GameResponse:
      properties:
        id:
          type: string
          title: Id
          description: >-
            The game's id. A live_event row's id is what a sports monitor takes
            as game_id; a schedule_table row's id belongs to the football
            schedule table and no monitor accepts it.
        league:
          type: string
          title: League
          description: League id, such as NBA.
        start_time:
          type: string
          format: date-time
          title: Start Time
        status:
          $ref: '#/components/schemas/GamePhase'
          description: scheduled, live, or final.
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: The event's own name. The only label F1 and NASCAR rows carry.
        home:
          anyOf:
            - $ref: '#/components/schemas/GameTeam'
            - type: 'null'
          description: Null for events without teams, such as F1 and NASCAR.
        away:
          anyOf:
            - $ref: '#/components/schemas/GameTeam'
            - type: 'null'
        odds_available:
          type: boolean
          title: Odds Available
          description: >-
            True when the game document already holds a market. Prematch odds
            arrive inside a per-sport window, so a game further out reports
            false until that window opens. A monitor create works either way; a
            game with a market is validated against the line it holds now.
        source:
          $ref: '#/components/schemas/GameSource'
          description: >-
            live_event for a game the live pipelines cover, schedule_table for
            an FBS or FCS game that only the football schedule table records.
            Only live_event rows can carry odds.
      type: object
      required:
        - id
        - league
        - start_time
        - status
        - title
        - home
        - away
        - odds_available
        - source
      title: GameResponse
      description: A game in the listing window.
    APIErrorType:
      type: string
      enum:
        - BAD_REQUEST
        - AUTHENTICATION_ERROR
        - INTERNAL_SERVER_ERROR
        - RELEVANT_RESULTS_NOT_FOUND
        - RATE_LIMIT_EXCEEDED
        - PAYMENT_REQUIRED
        - REQUEST_TIMEOUT
        - FORBIDDEN
        - NOT_FOUND
        - SERVICE_UNAVAILABLE
        - SERVICE_OVERLOADED
        - UNSUPPORTED_CONTENT_FORMAT
      title: APIErrorType
    GamePhase:
      type: string
      enum:
        - scheduled
        - live
        - final
      title: GamePhase
    GameTeam:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: >-
            The team's id, the team table's unique_id. Null for a placeholder
            side.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Display name. Null when the feed didn't carry one.
      type: object
      required:
        - id
        - name
      title: GameTeam
      description: One side of a game.
    GameSource:
      type: string
      enum:
        - live_event
        - schedule_table
      title: GameSource
      description: >-
        Which table a row came from, which decides what its id is good for.


        A ``live_event`` row's id is a ScheduledEvent key, the id a sports
        monitor takes as

        ``game_id``. A ``schedule_table`` row is an FBS or FCS game, which no

        ScheduledEvent pipeline covers: its id belongs to the football schedule

        table, no live document exists for it, and no monitor accepts it.
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````