# List games

Source: https://langbot.ai/docs/api/sports/list-games

`GET /v1/sports/games`

NBA, NHL and MLB games of a day with their score, period and clock on Langbot's clock, and the Kalshi and Polymarket markets linked to each.

**Auth.** None. Without a token the call is served as Free (the Free delay and request budget, shared per IP); send `Authorization: Bearer lb_…` for your plan's.

**Limits.** Counts against your plan's API requests (60, 600 or 3,000 a minute on Free, Builder and Standard). Served at your plan's delay (+60 s Free, +10 s Builder, +2 s Standard).

## Parameters

### Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `league` | string | no | Comma-separated: `nba`, `nhl`, `mlb`. |
| `date` | string | no | The league's game date, `YYYY-MM-DD` (default today, US Eastern). |
| `status` | string | no | Comma-separated: `scheduled`, `live`, `final`, `postponed`, `cancelled`, `suspended`. |
| `ticker` | string | no | A Kalshi market or event ticker (`KXNHLGAME-26NOV07VANEDM-EDM`), a Polymarket slug or `pm_<id>`: the game it is linked to, any date. |
| `links` | boolean | no | `true` to include each game's venue links. Default `false`. |
| `limit` | integer | no | Page size. 1 to 500. Default `100`. |

## Request

**curl**

```bash
curl "https://api.langbot.ai/v1/sports/games?league=nhl&date=2026-11-07&status=live"
```

**Python**

```python
from langbot import LangbotClient

async with LangbotClient() as lb:
    for g in await lb.sports_games(league="nhl", date="2026-11-07", status="live"):
        print(g.title, g.away.score, g.home.score, g.period, g.clock, g.markets)
```

**TypeScript**

```ts
import { LangbotClient } from "@langbotai/sdk";

const lb = new LangbotClient();
const games = await lb.sportsGames({ league: "nhl", date: "2026-11-07", status: "live" });
for (const g of games) console.log(g.title, g.away.score, g.home.score, g.clock);
```

## Response

`200 OK`

```json
{
  "ts": 1794113400000,
  "date": "2026-11-07",
  "league": "nhl",
  "delay_ms": 0,
  "count": 1,
  "games": [
    {
      "id": "nhl_2026020276",
      "league": "nhl",
      "game_id": "2026020276",
      "event_id": "ev_sports_nhl_2026020276",
      "date": "2026-11-07",
      "start_time": 1794106800000,
      "title": "VAN @ EDM",
      "away": {"code": "VAN", "name": "Vancouver Canucks", "score": 1},
      "home": {"code": "EDM", "name": "Edmonton Oilers", "score": 1},
      "status": "live",
      "status_detail": null,
      "period": 3,
      "period_type": "REG",
      "clock": "14:21",
      "score_at": 1794110943512,
      "markets": {"kalshi": 9, "polymarket": 1},
      "linked": null
    }
  ]
}
```

Scores come from the leagues' own live data (NHL and MLB; NBA when its feed admits Langbot) and are what your plan's delay lets you see: score, status, period and clock are those of the last game event visible to you, and `score_at` is when Langbot detected that score. `event_id` is the game's key on the live stream (`types=score_changed,game_status` or the event id), in [recent events](https://langbot.ai/docs/api/live-events/list-recent-events) and in the Sim replay. `markets` counts the linked venue events (game, spread, total, periods, player props on Kalshi; the game's event on Polymarket). NFL and college games are not covered.

## Errors

| Status | `code` | When |
|---|---|---|
| 422 | `validation_error` | An unknown league or status, or a date that is not `YYYY-MM-DD`. |
| 401 | `token_invalid` | A token was sent and not recognised. Send a valid one, or none to call anonymously. |
| 429 | `rate_limited` | Over your request budget; wait `Retry-After` seconds. |

Every error body is `{"detail": …, "code": "…"}`; branch on `code`. All codes: [Errors](https://langbot.ai/docs/api#errors).