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

# List League Games

> All tracked games for a polynode league code, with optional live-only filter.

Returns every game we currently have in the state store for a given polynode league code. Useful for building league-level dashboards. Combine with the optional `live=true` query flag to filter to only in-play games.

```bash theme={null}
# all games for the league (live, unplayed, final)
curl -s "https://books.polynode.dev/v1/leagues/lib/games?key=pn_live_YOUR_KEY"

# only in-play games
curl -s "https://books.polynode.dev/v1/leagues/lib/games?live=true&key=pn_live_YOUR_KEY"
```

<ParamField path="code" type="string" required>
  Polynode league code (`nba`, `nhl`, `epl`, `lib`, `ipl`, `ufc`, `atp`, `lol`, `cs2`, etc.). See the polynode [List Leagues](/api-reference/sports/leagues) endpoint for the complete list of codes.
</ParamField>

<ParamField query="live" type="boolean" default="false">
  Filter to only games where `scores.is_live == true`. Default returns every game we have cached for the league.
</ParamField>

<ParamField query="key" type="string" required>
  Your API key.
</ParamField>

## Response

```json theme={null}
{
  "league": "lib",
  "count": 2,
  "games": [
    {
      "game_id": "40664-16839-2026-04-14",
      "pn_slug": "lib-gar-est-2026-04-14",
      "pn_league_code": "lib",
      "sport_category": "soccer",
      "start_date": "2026-04-14T22:00:00Z",
      "status": "live",
      "venue": "Estadio Jorge Luis Hirschi",
      "home_team": {
        "name": "Club Estudiantes de La Plata",
        "abbreviation_pn": "est"
      },
      "away_team": {
        "name": "Cusco FC",
        "abbreviation_pn": "gar"
      },
      "scores": {
        "status": "Live",
        "score_home": 2,
        "score_away": 1,
        "period": "2H",
        "clock": "50",
        "is_live": true
      }
    },
    {
      "game_id": "...",
      "pn_slug": null,
      "pn_league_code": "lib",
      "home_team": { "name": "Club Nacional de Football" },
      "away_team": { "name": "Club Deportes Tolima SA" },
      "scores": {
        "score_home": 1,
        "score_away": 0,
        "period": "2H",
        "clock": "51",
        "is_live": true
      }
    }
  ]
}
```

## Top-level shape

| Field    | Type    | Description                                                                                      |
| -------- | ------- | ------------------------------------------------------------------------------------------------ |
| `league` | string  | Echo of the path parameter.                                                                      |
| `count`  | integer | Number of games returned after any filtering.                                                    |
| `games`  | array   | Full game objects, same shape as [List Live Games](/api-reference/books/games-live#game-object). |

## Notes

* Only games we have ingested at least once are returned. If the league's upstream source has not yet been polled, the response will have `count: 0`.
* Passing an unmapped league code (not in our 107-entry league map) returns `count: 0` rather than an error. The service does not distinguish "we don't track this league" from "this league has no active games" at the response layer.
* For games where our team resolver could not match both teams to polynode's roster, `pn_slug` will be `null`. The game still appears in the list with its raw `game_id`.
* Games expire from the cache 24 hours after their last update.